Class Geolocation

Check permissions status for geolocation resource

Example:

const geolocationStatus = await Eitri.geolocation.checkPermission({precision: "precise"})
console.log(geolocationStatus)

/* Example output from this console.log:
   {
       status: "DENIED",
       details: {
           precision: "precise"
       }
   } 
*/
Copy

🚨 Android only: If executed before the first permission request, the default response is BLOCKED.

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Fallback: API LEVEL 16 - Legacy implementation (deprecated)

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation) {
  // Module-based implementation available
}
Copy

Request permission for geolocation resource

Example:

const geolocationStatus = await Eitri.geolocation.requestPermission({precision: "approximate"})
console.log(geolocationStatus)

/* Example output from this console.log:
   {
       status: "GRANTED",
       details: {
           precision: "approximate"
       }
   } 
*/
Copy

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Fallback: API LEVEL 16 - Legacy implementation (deprecated)

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation) {
  // Module-based implementation available
}
Copy

Get the current location of the device

Example:

try {
  const geolocationStatus = await Eitri.geolocation.requestPermission({precision: "precise"})

  if (geolocationStatus.status == "GRANTED") {
    const location = await Eitri.geolocation.getCurrentLocation()
    console.log(location)
     /* Example output from this console.log:
       {
           "latitude": -22.9576466,
           "longitude": -43.1760832
       }
     */
    return
  }

  // handle other permission states
  // inform user

} catch (e) {
  console.log(e)
  // handle errors and notify user
}

Copy

• use openAppSettings to handle BLOCKED situations

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Fallback: API LEVEL 16 - Legacy implementation (deprecated)

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation) {
  // Module-based implementation available
}
Copy

Upgrade to background location permission (Always/Background access)

This method requests permission to access location when the app is in the background.

Prerequisites:

• Foreground/when-in-use permission must already be granted
  • Will throw error if foreground permission not granted

Platform-specific behavior:

• Android
  • Shows system dialog for background location access
• iOS
  • Shows "Change to Always Allow" dialog if when-in-use already granted

const modules = await Eitri.modules();
const upgradeToBackgroundPermission = modules?.geolocation?.upgradeToBackgroundPermission;

if (!upgradeToBackgroundPermission) {
  console.log("upgradeToBackgroundPermission is not available");
  return;
}

// First ensure foreground permission
const foreground = await Eitri.geolocation.requestPermission({precision: "precise"});

if (foreground.status === "GRANTED") {
  // Then upgrade to background
  const background = await Eitri.geolocation.upgradeToBackgroundPermission();

  if (background.details.backgroundPermission === true) {
    console.log("Background permission granted");
  } else {
    console.log("Background permission denied");
  }
}
Copy

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Module API LEVEL 2
• Fallback: UNAVAILABLE

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation) {
  // Module-based implementation available
}
Copy

Forward-geocode an address, place name, or other free-form text into one or more GeocodingPlaces containing coordinates and structured address fields.

Returns a best-effort, localised set of matches: not all address fields are always populated, and ordering is the platform's relevance order.

Example:

const modules = await Eitri.modules();
if (!modules?.geolocation?.forwardGeocode) {
  console.log("Geocoding requires the geolocation module API LEVEL 3 or newer");
  return;
}

const places = await Eitri.geolocation.forwardGeocode({
  query: "1600 Amphitheatre Pkwy, Mountain View, CA",
  maxResults: 1,
  locale: "en-US"
});

console.log(places[0]);
/* Example output:
  {
    latitude: 37.4220656,
    longitude: -122.0840897,
    name: "Googleplex",
    street: "Amphitheatre Pkwy",
    locality: "Mountain View",
    administrativeArea: "California",
    postalCode: "94043",
    country: "United States",
    countryCode: "US",
    formattedAddress: "1600 Amphitheatre Pkwy, Mountain View, CA 94043, United States"
  }
*/
Copy

🚨 Android: The native geocoder relies on a backend service that is not present on every device (notably some China-region OEMs ship without it). When unavailable, the call rejects with Eitri.Geolocation.Geocoding.unavailable.

🚨 iOS: Apple throttles geocoding requests (roughly one per user action). Avoid bursts such as geocoding-as-the-user-types — debounce on the eitri-app side.

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Module API LEVEL 3

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation?.forwardGeocode) {
  // Geocoding methods are available
}
Copy

Reverse-geocode a pair of coordinates into one or more GeocodingPlaces containing structured address fields.

Returned places are ordered by the platform's relevance heuristic and may omit fields that the provider could not resolve.

Example:

const modules = await Eitri.modules();
if (!modules?.geolocation?.reverseGeocode) {
  console.log("Geocoding requires the geolocation module API LEVEL 3 or newer");
  return;
}

const places = await Eitri.geolocation.reverseGeocode({
  latitude: -23.5613,
  longitude: -46.6565,
  maxResults: 1,
  locale: "pt-BR"
});

console.log(places[0]);
/* Example output:
  {
    latitude: -23.5613,
    longitude: -46.6565,
    street: "Avenida Paulista",
    locality: "São Paulo",
    administrativeArea: "São Paulo",
    country: "Brasil",
    countryCode: "BR",
    formattedAddress: "Avenida Paulista, São Paulo - SP, Brasil"
  }
*/
Copy

🚨 Android: When unavailable, the call rejects with Eitri.Geolocation.Geocoding.unavailable.

🚨 iOS: Apple throttles geocoding requests (roughly one per user action). Avoid bursts such as geocoding-as-the-user-types — debounce on the eitri-app side.

Compatibility Control

• Module: geolocation - Install eitri-ios-geolocation or eitri-android-geolocation
• Module API LEVEL 3

Check module availability:

const modules = await Eitri.modules();
if (modules?.geolocation?.reverseGeocode) {
  // Geocoding methods are available
}
Copy