Использование Geolocation API

Объект геолокации

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

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

if ("geolocation" in navigator) {
  /* местоположение доступно */
} else {
  /* местоположение НЕ доступно */
}

Получение текущего местоположения

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

navigator.geolocation.getCurrentPosition(function (position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

Функция do_something(), в примере выше, будет вызвана лишь тогда, когда данные о местоположении будут получены.

Наблюдение за текущим местоположением

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

var watchID = navigator.geolocation.watchPosition(function (position) {
  do_something(position.coords.latitude, position.coords.longitude);
});

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

navigator.geolocation.clearWatch(watchID);

Точная настройка отклика

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

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

Вызов watchPosition может выглядит следующим образом:

function geo_success(position) {
  do_something(position.coords.latitude, position.coords.longitude);
}

function geo_error() {
  alert("Извините, нет доступной позиции.");
}

var geo_options = {
  enableHighAccuracy: true,
  maximumAge: 30000,
  timeout: 27000,
};

var wpid = navigator.geolocation.watchPosition(
  geo_success,
  geo_error,
  geo_options,
);

Описание позиции

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

Экземпляр GeolocationPosition содержит только две вещи, свойство coords, внутри которого GeolocationCoordinates и свойство timestamp, внутри которого экземпляр DOMTimeStamp, предоставляющее метку времени, созданную при получении данные.

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

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

  // Дальше код, который что-то делает с широтой(latitude) и долготой(longitude)
}

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

Обработка ошибок

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

Функция может выглядеть примерно так:

function errorCallback(error) {
  alert("ERROR(" + error.code + "): " + error.message);
}

Примеры

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

body {
  padding: 20px;
  background-color: #ffffc9;
}

button {
  margin: 0.5rem 0;
}

HTML

<button id="find-me">Show my location</button><br />
<p id="status"></p>
<a id="map-link" target="_blank"></a>

JavaScript

function geoFindMe() {
  const status = document.querySelector("#status");
  const mapLink = document.querySelector("#map-link");

  mapLink.href = "";
  mapLink.textContent = "";

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

    status.textContent = "";
    mapLink.href = `https://www.openstreetmap.org/#map=18/${latitude}/${longitude}`;
    mapLink.textContent = `Широта: ${latitude} °, Долгота: ${longitude} °`;
  }

  function error() {
    status.textContent = "Невозможно получить ваше местоположение";
  }

  if (!navigator.geolocation) {
    status.textContent = "Geolocation не поддерживается вашим браузером";
  } else {
    status.textContent = "Определение местоположения…";
    navigator.geolocation.getCurrentPosition(success, error);
  }
}

document.querySelector("#find-me").addEventListener("click", geoFindMe);

Демо