Руководство Javascript Geolocation API

Geolocation API
PositionOptions interface
Geolocation interface
Position interface
Coordinates interface
PositionError interface

1. Geolocation API

Geolocation API включает интерфайсы помогающие вам определить местонахождение пользователя, который использует браузер на данный момент, и вы можете взаимодействовать с данными интерфейсами через Javascript. Это позволяет website или приложению предоставить кастомизированное содержаие в зависимости от местонахождения пользователя.

В основном Geolocation API включает разные интерфейсы:

Geolocation
PositionOptions
Position
Coordinates
PositionError

Когда Geolocation API пытается получить местонахождение пользователя, браузер отображает диалог спрашивающее разрешение пользователя. Заметьте, что каждый браузер имеет свои правила и методы для данного запроса.

geolocation-example.js

// Success Handler
function successHandler(position)  {
  var logArea = document.getElementById("log-area");

  logArea.value = "";
  logArea.value += "Latitude: " + position.coords.latitude + "\n";
  logArea.value += "Longitude: " + position.coords.longitude + "\n";
}

// Error Handler
function errorHandler(positionError)  {
   if(positionError.code == 1) { // PERMISSION_DENIED
       alert("Error: Permission Denied! " + positionError.message);
   } else if(positionError.code == 2) { // POSITION_UNAVAILABLE
       alert("Error: Position Unavailable! " + positionError.message);
   } else if(positionError.code == 3) { // TIMEOUT
       alert("Error: Timeout!" + positionError.message);
   }
}

function showInfos()  {
  navigator.geolocation.getCurrentPosition(successHandler, errorHandler);
}

geolocation-example.html

<!DOCTYPE html>
<html>
   <head>
      <title>Geolocation</title>
      <meta charset="UTF-8">
      <style>textarea {width:100%;margin-top:10px;}</style>

      <script src="geolocation-example.js"></script>
   </head>
   <body>

       <h1>Geolocation</h1>

       <button onClick="showInfos()">Show Infos</button>

        <textarea name="name" rows="5" id="log-area"></textarea>
   </body>
</html>

2. PositionOptions interface

PositionOptions это интерфейс, описывающий объект с необязательными свойствами (property), данный объект может передаваться (pass) как параметр для метода Geolocation.getCurrentPosition() или Geolocation.watchPosition().

var options = {
    maximumAge : 1000,
    timeout: 5000,
    enableHighAccuracy : true
};

PositionOptions имеет 3 свойства (property):

maximumAge
timeout
enableHighAccuracy

maximumAge

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

timeout

Время в милисекундах это максимум, что программа ждет для определения местоположения пользователя. Если в тот период времени невозможно определить местоположение пользователя, то считается неуспешным и вызывается функция Callback-error.

enableHighAccuracy

Значение данного параметра это true/false. Значение true означает программа пытается найти местоположение наилучшим способом, например телефон имеет chip GPS, он будет использован для более точного определения местоположения, это потребует больше времени и энергии. По умолчанию false.

3. Geolocation interface

Geolocation это самый важный интерфейс в Geolocation API, вы можете получить доступ через свойство (property) navigator.geolocation.

navigator.geolocation

// Geolocation object:
var geo = navigator.geolocation;
 
// Or:
var geo = window.navigator.geolocation;

Методы Geolocation:

getCurrentPosition()
watchPosition()
clearWatch()

getCurrentPosition(success[,error[, [options]])

Метод getCienPocation() используется для получения текущего местоположения устройства.

// success: A Callback function
// error: A Callback function (Optional)
// options: PositionOptions object (Optional)

getCurrentPosition(success[, error[, [options]])

// position: Position object.
var success = function(position)  {

}

//  positionError: PositionError object.
var error = function( positionError )  {

}

Параметры:

success

Функция Callback имеет параметр это position (Объект интерфейса Position), он вызывается когда все успешно, включая когда пользователь разрешает Geolocation API определить свое местоположение и данный API может определить местоположение пользователя.

error

Функция Callback с параметром positionError (Объект интерфейса PositionError), вызывается когда пользователь не разрешает Geolocation API увидеть свое местоположение, или не может определить местоположение пользователя, или timeout.

options

Является объектом интерфейса PositionOptions. Включая опции:

maximumAge
timeout
enableHighAccuracy

** Смотрите так же спецификации про интерфейс PositionOptions в данном документе.

watchPosition(success[, error[, options]])

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

// success: A Callback function
// error: A Callback function (Optional)
// options: PositionOptions object (Optional)

// watchID: An Integer Number.
var watchID = watchPosition(success[, error[, [options]])

// position: Position object.
var success = function(position)  {

}

//  positionError: PositionError object.
var error = function( positionError )  {

}

Параметры:

success

Функция Callback имеет параметр position (Объект интерфейса Position), вызывается когда все успешно, включая когда пользователь разрешает Geolocation API определить свое местоположение, и данный API успешно определяет местоположение пользователя.

error

options

Являет объектом интерфейса PositionOptions. Включая опции:

maximumAge
timeout
enableHighAccuracy

** Смотрите так же спецификации про интерфейс PositionOptions в данной статье.

clearWatch(id)

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

4. Position interface

Интерфейс Position содержит такую информацию как местоположение и время получения данных местоположения устройства.

Properties:

position.coords

Возвращает объект Coordinates хранящий информацию долготы (longitude), широты (latitude), высоты (altitude) устройства относительно уровню моря Земли.

position.timestamp

Возвращает объект DOMTimeStamp представляющий время, когда было получено местоположение.

5. Coordinates interface

Интерфейс Coordinates представляет положение и высоту (altitude) устройства относительно уровню моря Земли, так же точность с которой данные свойства (property) были расчтаны.

latitude

Возвращает число описывающее широту (latitude) в "десятичных градусах" (decimal degrees). Его значение находится в диапазоне [-90,90]

longitude

Возвращает число описывающее долготу (longitude) в "десятичных градусах" (decimal degrees). Его значение находится в диапазоне [-180,180].

altitude

Возвращает число описывающее высоту (altitude) местоположения в метрах, относительно уровня моря. Это значение может быть null если выполнение не может предоставить данные.

accuracy

Возвращает число представляющее точность свойств (property) долготы и широты, выраженное в метрах.

altitudeAccuracy

Возвращает число представляющее точность высоты в метрах. Это значение может быть null.

heading

Возвращает число представляющее направление, в котором двигается устройство. Данное значение указывается в градусах (degrees), дает знать насколько далеко от Севера находится устройство. Значение 0 градусов представляет настоящий Север, а направление определяется по часовой стрелке (то есть восток равен 90 градусам, а запад - 270 градусам). Если скорость равна 0, тогда значение heading является NaN.. Если устройство не может предоставить информацию heading, это значение является null.

speed

Возвращает число представляющее скорость устройства в метрах в секунду. Это значение может быть null.

6. PositionError interface

Интерфейс PositionError представляет причину происхождения ошибки при использовании устройства геолокации.

Значение	Константа	Описание
1	PERMISSION_DENIED	Неуспешное получение информации Geolocation так как пользователь не разрешил доступ к своему местоположению.
2	POSITION_UNAVAILABLE	Неуспешное получение информации Geolocation так как на стороне поставщика географической информации произошла внутренняя ошибка.
3	TIMEOUT	Запрос на получение информации о местоположении отправлен, и после превышения допустимого времени результаты еще не получены. Следовательно, запрос отменяется и считается неудачным. PositionOptions.timeout позволяет вам конфигурировать максимальное время ожидания ответа.