위치정보 요청 및 응답

Geolocation 요청

Geolocation 요청은 POST를 사용하여 다음과 같은 URL로 전송됩니다.

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

요청에서 key 매개변수의 값으로 포함하여 키를 지정해야 합니다. key는 애플리케이션의 API 키입니다. 이 키는 할당량 관리를 위해 애플리케이션을 식별합니다. 키를 가져오는 방법을 알아보세요.

요청 본문

요청 본문은 JSON 형식으로 지정되어야 합니다. 요청 본문이 포함되지 않은 경우 요청 위치의 IP 주소를 기반으로 결과가 반환됩니다. 다음과 같은 필드가 지원되며, 달리 명시되지 않는 한 모든 필드는 선택 항목입니다.

Geolocation API 요청 본문의 예는 다음과 같습니다.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

휴대폰 기지국 객체

요청 본문의 cellTowers 배열에는 0개 이상의 휴대폰 기지국 객체가 포함됩니다.

다음 선택사항 필드는 사용되지 않지만 값을 사용할 수 있는 경우 포함될 수 있습니다.

cellId 계산

NR (5G) 이전의 무선 유형은 32비트 cellId 필드를 사용하여 네트워크 셀 ID를 Geolocation API에 전달합니다.

• GSM (2G) 네트워크는 16비트 Cell ID (CID)를 있는 그대로 사용합니다. 유효 범위: 0~65535.
• CDMA (2G) 네트워크는 16비트 기지국 ID (BID)를 있는 그대로 사용합니다. 유효 범위: 0~65535.
• WCDMA (3G) 네트워크는 12비트 무선 네트워크 컨트롤러 식별자 (RNC-ID)와 16비트 셀 ID (CID)를 연결한 28비트 정수 값인 UTRAN/GERAN 셀 ID (UC-ID)를 사용합니다.
  수식: rnc_id << 16 | cid.
  유효 범위: 0~268435455
  참고: WCDMA 네트워크에서 16비트 Cell ID 값만 지정하면 잘못된 결과 또는 0이 반환됩니다.
• LTE (4G) 네트워크는 20비트 E-UTRAN 노드 B 식별자 (eNBId)와 8비트 셀 ID (CID)를 연결한 28비트 정수 값인 E-UTRAN 셀 ID (ECI)를 사용합니다.
  수식: enb_id << 8 | cid.
  유효 범위: 0~268435455
  참고: LTE 네트워크에서 8비트 Cell ID 값만 지정하면 잘못된 결과 또는 0 결과가 반환됩니다.

API 요청에 이 범위를 벗어난 값을 배치하면 정의되지 않은 동작이 발생할 수 있습니다. API는 문서화된 범위에 맞게 숫자를 자르거나, radioType의 수정사항을 추론하거나, 응답에 표시기 없이 NOT_FOUND 결과를 반환할 수 있습니다(Google의 재량에 따름).

LTE 셀 타워 객체의 예는 다음과 같습니다.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

newRadioCellId 계산

셀 ID가 32비트보다 긴 최신 네트워크는 64비트 newRadioCellId 필드를 사용하여 네트워크 셀 ID를 Geolocation API에 전달합니다.

• NR (5G) 네트워크는 36비트 New Radio Cell Identity (NCI)를 있는 그대로 사용합니다.
  유효 범위: 0~68719476735

아래는 예시 NR 휴대폰 기지국 객체입니다.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

WiFi 액세스 지점 객체

요청 본문의 wifiAccessPoints 배열에는 물리적으로 구별되는 액세스 지점 기기를 나타내는 WiFi 액세스 지점 객체가 2개 이상 포함되어야 합니다. macAddress는 필수사항이고 다른 필드는 모두 선택사항입니다.

아래는 예시 WiFi 액세스 지점 객체입니다.

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

샘플 요청

샘플 데이터로 Geolocation API를 사용해 보고 싶으면 다음 JSON을 파일에 저장합니다.

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

그런 다음 cURL을 사용하여 명령줄에서 요청할 수 있습니다.

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

위의 MAC 주소에 대한 응답은 다음과 같습니다.

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

사용하지 않는 Wi-Fi 액세스 포인트 삭제

로컬에서 관리되는 macAddress를 사용하여 Wi-Fi 액세스 포인트 객체를 삭제하면 Wi-Fi를 입력으로 사용하는 Geolocation API 호출의 성공률을 개선할 수 있습니다. 필터링 후 위치정보 API 호출이 성공하지 않을 것으로 확인되면 이전 위치 신호를 사용하거나 신호가 약한 Wi-Fi AP를 사용하는 등의 완화 조치를 사용할 수 있습니다. 이 접근 방식은 애플리케이션의 위치 추정치 요구사항과 정확성 및 재현 요구사항 간의 절충입니다. 다음 필터링 기법은 입력을 필터링하는 방법을 보여 주지만 애플리케이션 엔지니어가 적용할 수 있는 완화 조치는 보여주지 않습니다.

로컬에서 관리되는 MAC 주소는 API에 유용한 위치 신호가 아니며 요청에서 자동으로 삭제됩니다. macAddress의 최상위 바이트의 두 번째 최하위 비트를 0(예: 02:00:00:00:00:00의 2로 표시된 1비트)로 설정하여 이러한 MAC 주소를 삭제할 수 있습니다. 브로드캐스트 MAC 주소(FF:FF:FF:FF:FF:FF)는 이 필터에서 유용하게 제외할 수 있는 MAC 주소의 예입니다.

00:00:5E:00:00:00과 00:00:5E:FF:FF:FF 사이의 MAC 주소 범위는 IANA용으로 예약되어 있으며, 위치 신호로 사용할 수 없도록 하는 네트워크 관리 및 멀티캐스트 기능에 사용되는 경우가 많습니다. API 입력에서 이러한 MAC 주소도 삭제해야 합니다.

예를 들어 GeoLocation에 사용할 수 있는 MAC 주소는 macs라는 macAddress 문자열 배열에서 수집할 수 있습니다.

String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16))
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

이 필터를 사용하면 목록에 1c:34:56:78:9a:bc만 남게 됩니다. 이 목록에는 Wi-Fi MAC 주소가 2개 미만이므로 요청이 성공하지 않고 HTTP 404 (notFound) 응답이 반환됩니다.

Geolocation 응답

위치 정보 요청이 성공하면 위치와 반경을 정의하는 JSON 형식의 응답이 반환됩니다.

• location: 사용자의 예상 위도 및 경도 좌표(도)입니다. 하나의 lat 및 하나의 lng 하위 필드를 포함합니다.
• accuracy: 예상 위치의 정확도입니다(미터 단위). 이 값은 지정된 location 주변의 원의 반지름을 나타냅니다.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}