Skip to main content

Geolocation

The Geolocation utility module provides a comprehensive set of functions for working with location data, including retrieval of user positions, coordinate parsing, and generation of map service links. These utilities simplify location-based features within your application and enable seamless integration with popular mapping services. Available since version 1.9.2.

Also read the blog article Share location

Get current position​

The getCurrentPosition() method provides a modern, Promise-based wrapper around the browser's native navigator.geolocation.getCurrentPosition() API. This implementation simplifies error handling by standardizing error objects with appropriate name properties, making it easier to identify and respond to specific geolocation errors in your application. The returned Promise resolves with the user's coordinates or rejects with a detailed error when location access fails.

import { Geolocation } from '@eyeson/js';

try {
    const { latitude, longitude } = await Geolocation.getCurrentPosition();
} catch (error) {
    if (error.name === 'NotAllowedError') {
        console.log('The page didn\'t have the necessary permissions, for example because it is blocked.');
    }
    else if (error.name === 'PositionUnavailableError') {
        console.log('Geolocation failed because at least one internal source of position returned an internal error.');
    }
    else if (error.name === 'TimeoutError') {
        console.log('The time allowed to acquire the geolocation was reached.');
    }
}
note

The result also contains accuracy, altitude, heading, and speed. See: https://developer.mozilla.org/en-US/docs/Web/API/GeolocationCoordinates

Error​

The error object returned when getCurrentPosition() rejects is a standard GeolocationPositionError. This allows you to use the traditional code property to identify specific error types, providing an alternative approach to the name-based error handling.

if (error instanceof GeolocationPositionError) {
    switch (error.code) {
        case GeolocationPositionError.PERMISSION_DENIED:
            break;
        case GeolocationPositionError.POSITION_UNAVAILABLE:
            break;
        case GeolocationPositionError.TIMEOUT:
            break;
    }
}

Check support​

The geolocation support check can be found in FeatureDetector. It can be used together with Geolocation.getCurrentPosition().

import { FeatureDetector } from '@eyeson/js';

const isSupported = FeatureDetector.canGeolocation();

Permission check​

The getPermissionStatus() method returns the current permission state for location access. This can be called at any point before invoking Geolocation.getCurrentPosition() to check existing permissions. You can use this to provide appropriate UI guidance to users when permission is denied. The method returns a Promise that resolves to one of three states: 'prompt', 'granted', or 'denied'. If an error occurs during the permission check, the function defaults to returning 'prompt'.

import { Geolocation } from '@eyeson/js';

const state = await Geolocation.getPermissionStatus();
switch (state) {
    case 'prompt':
        break;
    case 'granted':
        break;
    case 'denied':
        break;
}

The Geolocation module provides helper functions to generate and parse location links for various mapping services. These utilities simplify the process of creating shareable location URLs and extracting coordinates from existing map links, enabling seamless integration with popular online mapping platforms.

Given latitude and longitude values, you can generate links to a number of common online maps services like Google Maps, etc.

import { Geolocation } from '@eyeson/js';

const latitude = 48.2154648; // double or string
const longitude = 16.397599; // double or string
const {
    what3words,
    googleMaps,
    openStreetMap,
    bingMaps,
    wegoHere
} = Geolocation.generateLinkFromCoordinates(latitude, longitude);

console.log(googleMaps); // https://www.google.com/maps/search/?api=1&query=48.2154648,16.397599

Extract latitude and longitude values from links of common online maps services.

Currently supported:

  • Google Maps
  • OpenStreetMap
  • Bing Maps
  • HERE WeGo
import { Geolocation } from '@eyeson/js';

if (Geolocation.linkContainsCoordinates(link)) {
    const { latitude, longitude } = Geolocation.parseCoordinatesFromLink(link);
}

// OR

const parsed = Geolocation.parseCoordinatesFromLink(link);
if (parsed !== null) {
    const { latitude, longitude } = parsed;
}