API Geolocation (Геолокация) — краткий справочник

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

Методы

В API Geolocation (Геолокация) предусмотрено три метода для получения географической информации от систем устройства:

— getCurrentPosition(location, error, configuration). При каждом вызове возвращает географическую информацию. Первый атрибут — это функция обратного вызова, предназначенная для получения информации, второй — еще одна функция обратного вызова для обработки ошибок, а третий — объект, содержащий конфигурационные значения (см. описание объекта конфигурации далее);

— watchPosition(location, error, configuration). Автоматически возвращает географическую информацию при каждом изменении местоположения. Первый атрибут — это функция обратного вызова, предназначенная для получения информации, второй — еще одна функция обратного вызова для обработки ошибок, а третий — объект, содержащий конфигурационные значения (см. описание объекта конфигурации далее);

— clearWatch(id). Отменяет процесс, запущенный методом watchPosi-tion(). Атрибут id — это идентификатор, возвращаемый при вызове метода watchPosition().

Объекты

Методы getCurrentPosition() и watchPosition() создают два объекта для передачи информации, полученной от геолокационной системы, а также статуса операции:

— Position. Создается для того, чтобы поместить в него информацию о местоположении. У него два атрибута: coords и timestamp:

— coords. Имеет несколько внутренних атрибутов, возвращающих информацию о местоположении: latitude (широта), longitude (долгота), altitude (высота, в метрах), accuracy (точность, в метрах), altitudeAccuracy (точность определения высоты, в метрах), heading (направление, в градусах) и speed (скорость, в метрах в секунду);

— timestamp. Возвращает время определения местоположения;

— PositionError. Создается, когда происходит ошибка. У него есть два обычных атрибута, содержащих код ошибки и сообщение об ошибке:

— message. Возвращает сообщение с описанием обнаруженной ошибки;

— error. Содержит код обнаруженной ошибки.

Также он предлагает три специальных значения для идентификации отдельных ошибок:

— PERMISSION_DENIED, значение 1 в атрибуте error. Равно true, когда пользователь запрещает API Geolocation (Геолокация) обращаться к географическим данным своего устройства;

— POSITION_UNAVAILABLE, значение 2 в атрибуте error. Равно true, когда невозможно определить местоположение устройства;

— TIMEOUT, значение 3 в атрибуте error. Равно true, если местоположение не удалось определить в течение времени, объявленного в конфигурации.

Методам getCurrentPosition() и watchPosition() для конфигурирования процесса требуется объект Configuration. Он предоставляет конфигурационные значения для методов getCurrentPosition() и watch-Position().

— enableHighAccuracy. Это один из возможных атрибутов объекта Configuration. Если его значение равно true, то браузер должен вернуть максимально точную географическую информацию;

— timeout. Это один из возможных атрибутов объекта Configuration. Указывает максимальную величину интервала, в течение которого операция должна быть выполнена;

— maximumAge. Это один из возможных атрибутов объекта Configuration. Указывает, как долго последнее кэшированное местоположение считается текущим.