위치정보 요청 및 응답

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": "lte",
  "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-ID)와 16비트 셀 ID (CID)를 연결하는 28비트 정수 값인 UTRAN/GERAN 셀 ID (UC-ID)를 사용합니다.
  수식: rnc_id << 16 | cid
  유효 범위: 0~268435455
  참고: WCDMA 네트워크에서 16비트 셀 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비트 셀 ID 값만 지정하면 잘못된 결과 또는 0개의 결과가 발생합니다.

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

요청 본문의 일부인 LTE 휴대폰 기지국 객체의 예는 다음과 같습니다.

{
  ...

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

이전 요청의 응답은 다음과 같습니다.

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

계산newRadioCellId

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

• NR (5G) 네트워크는 36비트 새 라디오 셀 ID (NCI)를 그대로 사용합니다.
  유효 범위: 0~68719476735

요청 본문의 일부인 NR 휴대폰 기지국 객체의 예는 다음과 같습니다.

{
  ...

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

이전 요청의 응답은 다음과 같습니다.

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

WiFi 액세스 지점 객체

요청 본문의 wifiAccessPoints 배열에는 실제로 서로 다른 고정 액세스 지점 기기를 나타내는 두 개 이상의 WiFi 액세스 지점 객체가 포함되어야 합니다. macAddress 필드는 필수입니다. 다른 모든 필드는 선택사항입니다. 이 서비스는 비행기 및 기차와 같이 이동하는 액세스 지점 을 무시합니다.

요청 본문의 일부인 WiFi 액세스 지점 객체의 예는 다음과 같습니다.

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

이전 요청의 응답은 다음과 같습니다.

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

샘플 요청

샘플 데이터로 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
}

사용되지 않는 WiFi 액세스 지점 삭제

macAddress가 브로드캐스트 주소 (FF:FF:FF:FF:FF:FF)이거나 IANA에서 예약한 WiFi 액세스 지점 객체를 삭제하면 WiFi를 입력으로 사용하는 Geolocation API 호출의 성공률을 높일 수 있습니다. 필터링 후 Geolocation API 호출 이 성공하지 않는 것으로 확인되면 이전 위치 신호 또는 신호가 약한 WiFi AP 를 사용하는 등의 완화 조치를 사용할 수 있습니다. 이 접근 방식은 위치 추정에 대한 애플리케이션의 요구사항과 정확도 및 재현율 요구사항 간의 절충입니다. 다음 필터링 기법은 입력을 필터링하는 방법을 보여주지만 애플리케이션 엔지니어가 적용할 수 있는 완화 조치는 보여주지 않습니다.

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

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

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

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

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

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

Geolocation 응답

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

• location: 사용자의 추정 위도 및 경도 좌표(도 단위)입니다. lat 및 lng 하위 필드가 하나씩 포함되어 있습니다.
• accuracy: 추정 위치의 정확도(미터)입니다. 이는 지정된 location을 중심으로 하는 원의 반경을 나타냅니다.

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

API는 입력 신호를 기반으로 위치와 정확도 반경을 반환합니다. API는 매우 정확한 위치를 반환할 수 있지만 정확도는 사용 가능한 신호의 소스, 수, 밀도, 강도에 따라 다를 수 있습니다. 일반적으로 다음과 같은 정확도 반경을 예상할 수 있습니다.

• WiFi 액세스 지점: 요청에 두 개 이상의 wifiAccessPoints가 포함된 경우 반환된 정확도 반경은 일반적으로 약 20미터입니다. 정확도는 액세스 지점 수와 신호 강도 (dBm으로 측정)에 따라 개선되며, 신호 강도는 일반적으로 -100~-20dBm 범위입니다.
• 휴대폰 기지국: WiFi 정보를 사용할 수 없거나 충분하지 않은 경우 API는 위치에 cellTowers를 사용합니다. 정확도는 휴대폰 기지국 유형, 신호 강도, 네트워크 밀도에 따라 크게 다릅니다.
  • 매크로 셀 (가장 일반적인 유형으로, 광범위한 영역에 사용됨)은 정확도가 낮습니다. 반경은 일반적으로 수백 미터 범위이며 휴대폰 기지국 연결 범위가 희박한 지역에서는 최대 수천 미터까지 될 수 있습니다. 매크로 셀의 경우 정확도 반경이 100미터 미만인 경우는 드뭅니다. 일반적으로 신호가 강한 휴대폰 기지국의 정확도가 더 높습니다. 강한 신호는 일반적으로 > -110dBm (신호 범위 -140~-55dBm), WCDMA의 경우 > -100dBm (신호 범위 -111~-53dBm), CDMA의 경우 > -100dBm (신호 범위 -120~-40dBm), GSM의 경우 > -80dBm (신호 범위 -121 ~-1dBm)입니다.
  • 소형 셀 (예: 펨토셀, 피코셀 또는 실내 리피터)은 가장 정확한 셀 기반 위치를 제공하며 정확도 반경은 10~30미터 범위일 수 있습니다.
• IP Geolocation: considerIp가 true 이고 WiFi 또는 휴대폰 기지국 신호를 Geolocation할 수 없는 경우 API는 요청의 IP 주소를 기반으로 위치를 추정합니다. 이 메서드는 정확도가 가장 낮으며 반경은 수천 미터일 수 있습니다. 문제 해결 가이드에서 정확도 반경이 매우 큰 이유는 무엇인가요? 정확도 반경이 매우 큰 이유는 무엇인가요?