[Geolocation API] 2. Geolocation API 공식 문서로 살펴보기

1. Geolocation API

HTML5에서 부터 제공되는 API입니다.
Geolocation API는 유저 동의 하에
웹 어플리케이션에서 위치 정보에 접근할 수 있는 API입니다.

navigator.geolocation

을 통해 Geolocation API에 접근할 수 있어요.
해당 API의 진입점이고, Geolocation 객체 인스턴스를 리턴해요.
위치 정보를 가져오는 방식은 2가지 다른 메서드로 제공돼요.

(1) 장치의 현재 위치 가져오기 (일시적) :

Geolocation.getCurrentPosition(param1, optionalParam2, optionalParam3)

(2) 기기의 위치가 바뀔때마다 새로운 위치 사용 (위치 바뀔때마다 등록된 함수 호출) :

Geolocation.watchPosition(param1, optionalParam2, optionalParam3)

두개 메서드의 매개변수는 3개로 동일해요.
(콜백 이름은 이해를 돕기 위해 임의로 작성했습니다 🤩)

매개변수1 onSuccess 콜백 (필수) - 위치 정보를 성공적으로 가져왔을 때, 위치 데이터를 담은 GeolocationPosition 객체만을 매개변수로 해당 콜백을 호출해줘요!

매개변수2 onError 콜백 (선택) - 위치 정보 가져오기에 실패했을 때, 실패 원인을 담은 GeolocationPositionError 객체를 매개변수로 해당 콜백을 호출합니다.

매개변수3 객체 (선택) - 위치 정보 회수를 위해 사용할 옵션을 3가지 지정할 수 있어요.

• maximumAge - 캐시에 저장한 위치정보를 대신 반환할 수 있는 최대 시간을 나타내는 양의 number(밀리초 기준, long)입니다. 0(default 값)을 지정한 경우 기기가 위치종보 캐시를 사용할 수 없기에 항상 실시간으로 위치를 확인해야할 것을 의미합니다. Infinity를 지정한 경우, 항상 캐시된 위치정보를 리턴하게 됩니다.
• timeout - 기기가 위치를 리턴할 때 소모할 최대 시간(밀리초, long)입니다. default는 Infinity로, 이때 위치를 알아내기 전까지 getCurrentPosition()이 반환되지 않습니다.
• enableHighAccuracy - 최고 정확도의 위치를 확인해야할 때 필요한 옵션입니다. bool값이고, default는 false입니다. true로 설정할 경우 reponse 속도가 늦고, 기기의 전력 소모량도 증가합니다.

2. Geolocation Interface

Geolocation 인터페이스는 Navigator 객체의 Geolocation속성으로 접근 가능합니다.
(*Navigator 인터페이스는 window.navigator read-only property(object)입니다. user agent의 상태 및 identity 정보를 제공합니다.)
Geolocation 인터페이스는 어떤 속성 및 메서드도 상속하지 않습니다.
웹 페이지에서 위치 정보에 접근을 시도하면 유저에서 알림을 보내고 권한 허용 여부에 대해 묻습니다.
Geolocation 인터페이스에서 제공하는 메서드는 3가지 입니다.

Geolocation.getCurrentPosition(param1, optionalParam2, optionalParam3)

Geolocation.watchPosition(param1, optionalParam2, optionalParam3); //watchId를 return합니다.

Geolocation.clearWatch(watchId); //watchPostion에서 return된 watchId를 매개변수로 넣어줍니다.

1. Geolocation.getCurrentPostion() 메서드

Geolocation.getCurrentPosition(successCallback, optionalErrorCallback, options) //options에 관해서는 1번 - 매개변수3을 확인해주세요.

• 장치의 현재 위치를 가져올 수 있어요
• 장치의 현재 위치를 확인한 후 GeolocationPostion 객체로 리턴합니다.
• W3C 명세

2. Geolocation.watchPostion() 메서드

Geolocation.watchPosition(successCallback, optionalErrorCallback, options) //options에 관해서는 1번 - 매개변수3을 확인해주세요.

• 기기의 위치가 바뀔 때마다 등록된 handler 함수가 자동으로 호출됩니다.
• 성공 시 callback함수의 매개변수로 GeolocationPostion 객체를 확인할 수 있습니다.
• watchPostition 메서드로 register된 handler id를 리턴합니다.
• 리턴된 handler id를 통해 unregister(기기 위치 추적 중단) 할 수 있습니다.

3.Geolocation.clearWatch() 메서드

Geolocation.clearWatch(id) 

• 매개변수는 Geolocation.watchPosition()메서드가 반환하는 handler(콜백) ID(number, 정수)
• Geolocation.watchPosition()메서드로 register한 handler를 unregister합니다.

• e.g.

let watchId = 0;

function success(pos) {
  const crd = pos.coords;
  console.log("success", crd);
  navigator.geolocation.clearWatch(watchId);
}

function error(err) {
  console.error(`ERROR(${err.code}): ${err.message}`);
}

const options = {
  enableHighAccuracy: false,
  timeout: 5000,
  maximumAge: 0,
};

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

3. Geolocation Position 인터페이스

주어진 시간(default는 Infinity)안에 유저 기기의 위치 정보를 알려줍니다.
위치정보는 Coordinates(en-US) 객체 (read-only)로 표현됩니다.

• geolocation.coords(Coordinates 객체) - latitude, longtitude, altitude, accuracy, speed 등의 data를 포함합니다.
• geolocation.timestamp(read-only, unix time, 밀리초) - device가 위치를 확인한 시간을 나타내는 DOMTimeStamp(en-US)입니다.
• 어떤 속성 및 메서도도 상속하지 않습니다.

• e.g.

navigator.getCurrentPosition((postition) => {
	console.log('위치정보 활용 성공');
    alert(position.coords.latitude, position.coords.longtitude)

}, onError, optionsObject)

4. Browser Compatibility 브라우저 호환성

출처

• MDN
• W3C 명세