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

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

Properties:

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