위치정보 요청 및 응답

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비트 셀 ID (CID)를 있는 그대로 사용합니다. 유효 범위는 0~65535입니다.
• CDMA(2G) 네트워크는 16비트 기지국 ID(BID)를 있는 그대로 사용합니다. 유효 범위: 0~65535.
• WCDMA(3G) 네트워크는 12비트 RNC 식별자(RNC-ID)와 16비트 셀 ID(CID)를 연결한 28비트 정수 값인 UTRAN/GERAN 셀 ID(UC-ID)를 사용합니다.
  수식: rnc_id << 16 | cid.
  유효 범위는 0~268435455입니다.
  참고: WCDMA 네트워크에서 16비트 셀 ID 값만 지정하면 다음과 같은 결과가 발생합니다. 결과를 얻지 못할 수도 있습니다.
• LTE (4G) 네트워크는 28비트 정수 값인 E-UTRAN Cell Identity (ECI)를 사용합니다. 20비트 E-UTRAN 노드 B 식별자 (eNBId)와 8비트 셀 ID (CID)를 연결합니다.
  수식: enb_id << 8 | cid.
  유효 범위는 0~268435455입니다.
  참고: LTE 네트워크에서 8비트 셀 ID 값만 지정하면 결과를 얻지 못할 수도 있습니다.

API 요청에서 이 범위 밖의 값을 배치하면 정의되지 않은 동작이 발생할 수 있습니다. API, Google의 재량에 따라 문서화된 범위에 맞도록 숫자를 자를 수 있으며, radioType 수정 없이 NOT_FOUND 결과를 반환 표시됩니다.

다음은 LTE 휴대폰 기지국 객체의 예입니다.

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

newRadioCellId 계산

셀 ID가 32비트보다 긴 최신 네트워크는 64비트 네트워크 셀 ID를 전달하기 위한 newRadioCellId 필드 Geolocation API

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

다음은 NR 휴대폰 기지국 객체의 예입니다.

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

WiFi 액세스 지점 객체

요청 본문의 wifiAccessPoints 배열에는 하나 이상의 와이파이 액세스 포인트 객체. 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에서 호출되고 요청에서 자동으로 삭제됩니다. 이러한 MAC 주소를 삭제할 수 있습니다. 두 번째로 가장 중요하지 않은 비트가 macAddress의 가장 중요한 바이트는 0입니다. 예: 1 비트 - 2 02:00:00:00:00:00입니다. 브로드캐스트 MAC 주소 (FF:FF:FF:FF:FF:FF)는 자동으로 제외됩니다.

MAC 주소 범위(00:00:5E:00:00:00~) 00:00:5E:FF:FF:FF: 예약됨 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만 검색됩니다. 표시됩니다. 이 목록에는 2개 미만의 Wi-Fi MAC 주소인 경우 요청이 성공하지 못하며 HTTP 404 (notFound) 응답이 반환됩니다.

Geolocation 응답

성공적인 위치정보 요청은 JSON 형식의 응답을 반환합니다. 위치와 반경을 정의합니다.

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

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