Использование API геолокации

API геолокации используется для получения местоположения пользователя, например, для отображения его позиции с помощью API карт. Эта статья объясняет основы его использования.

API геолокации доступен через объект navigator.geolocation.

Если объект существует, услуги геолокации доступны. Вы можете проверить наличие геолокации следующим образом:

if ("geolocation" in navigator) {
  /* geolocation is available */
} else {
  /* geolocation IS NOT available */
}

Чтобы получить текущее местоположение пользователя, можно вызвать метод getCurrentPosition(). Это инициирует асинхронный запрос для определения позиции пользователя и обращается к оборудованию определения местоположения, чтобы получить актуальную информацию. Когда позиция определена, выполняется определенная функция обратного вызова. Вы можете необязательно указать вторую функцию обратного вызова, которая выполнится в случае ошибки. Третий, необязательный параметр — объект options, где можно задать максимальный возраст возвращаемой позиции, время ожидания запроса и требуется ли высокая точность определения позиции.

navigator.geolocation.getCurrentPosition((position) => {
  doSomething(position.coords.latitude, position.coords.longitude);
});

Вышеприведенный пример вызовет выполнение функции doSomething() при получении местоположения.

Если данные о позиции изменяются (из-за перемещения устройства или если поступает более точная геоинформация), можно настроить функцию обратного вызова, которая вызывается с обновленными данными о позиции. Это делается с помощью функции watchPosition(), которая имеет те же входные параметры, что и getCurrentPosition(). Функция обратного вызова вызывается несколько раз, что позволяет браузеру обновлять ваше местоположение при движении или предоставлять более точное местоположение по мере использования различных методов геолокации. Функция обратного вызова ошибок, которая является необязательной, как и для getCurrentPosition(), может вызываться многократно.

const watchID = navigator.geolocation.watchPosition((position) => {
  doSomething(position.coords.latitude, position.coords.longitude);
});

Метод watchPosition() возвращает идентификатор, который можно использовать для уникальной идентификации наблюдателя позиции; это значение используется вместе с методом clearWatch() для прекращения отслеживания местоположения пользователя.

navigator.geolocation.clearWatch(watchID);

И getCurrentPosition(), и watchPosition() принимают функцию обратного вызова успеха, необязательную функцию обратного вызова ошибок и необязательный объект options.

Этот объект позволяет указать, включить ли высокую точность, максимальный возраст возвращаемой позиции (до этого возраста она будет кэшироваться и повторно использоваться, если запрашивается та же позиция; после этого браузер запросит свежие данные о позиции) и значение таймаута, которое определяет, как долго браузер должен пытаться получить данные о позиции, прежде чем произойдет таймаут.

Вызов watchPosition может выглядеть так:

function success(position) {
  doSomething(position.coords.latitude, position.coords.longitude);
}

function error() {
  alert("Sorry, no position available.");
}

const options = {
  enableHighAccuracy: true,
  maximumAge: 30000,
  timeout: 27000,
};

const watchID = navigator.geolocation.watchPosition(success, error, options);

Местоположение пользователя описывается с помощью экземпляра объекта GeolocationPosition, который сам содержит экземпляр объекта GeolocationCoordinates.

Экземпляр GeolocationPosition содержит только два элемента: свойство coords, которое содержит экземпляр GeolocationCoordinates, и свойство timestamp, которое содержит отметку времени, заданную как время Unix в миллисекундах, в которое были получены данные о позиции.

Экземпляр GeolocationCoordinates содержит ряд свойств, но два наиболее часто используемых — latitude и longitude, которые необходимы для отображения вашей позиции на карте. Поэтому многие функции обратного вызова успеха геолокации выглядят довольно просто:

function success(position) {
  const latitude = position.coords.latitude;
  const longitude = position.coords.longitude;

  // Do something with your latitude and longitude
}

Однако вы можете получить ряд других данных из объекта GeolocationCoordinates, включая высоту, скорость, направление, в котором смотрит устройство, а также точность данных о высоте, долготе и широте.

Функция обратного вызова ошибок, если она указана при вызове getCurrentPosition() или watchPosition(), принимает экземпляр объекта GeolocationPositionError в качестве первого параметра. Этот тип объекта содержит два свойства: code, указывающее на тип возвращенной ошибки, и удобочитаемое свойство message, описывающее значение кода ошибки.

Вы можете использовать его так:

function errorCallback(error) {
  alert(`ERROR(${error.code}): ${error.message}`);
}

В следующем примере API геолокации используется для получения широты и долготы пользователя. В случае успеха доступная гиперссылка заполняется ссылкой openstreetmap.org URL, отображающей его местоположение.