위치정보 요청 및 응답

Geolocation 요청

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

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

요청에 키( key 매개변수 key는 애플리케이션의 API 키입니다. 이 키는 할당량을 위해 애플리케이션을 식별합니다. 관리할 수 있습니다 키를 가져오는 방법을 알아보세요.

요청 본문

요청 본문은 JSON 형식으로 지정되어야 합니다. 요청 본문이 포함되지 않으면 결과 요청 위치의 IP 주소를 기준으로 반환됩니다. 다음 필드는 별도로 명시되지 않는 한 모든 입력란은 선택사항입니다.

필드 JSON 유형 설명 참고
homeMobileCountryCode number(uint32) 기기의 네트워크에 대한 모바일 국가 코드 (MCC)입니다. radioType gsm (기본값) 지원됨 wcdma, lte, nr cdma에 사용되지 않습니다.
유효 범위는 0~999입니다.
homeMobileNetworkCode number(uint32) 기기의 네트워크에 대한 모바일 네트워크 코드입니다. GSM, WCDMA, LTE, NR을 위한 MNC입니다.
CDMA는 SID (System ID)를 사용합니다.
MNC의 유효 범위는 0~999입니다.
SID의 유효 범위는 0~32767입니다.
radioType string 모바일 무선 유형입니다. 지원되는 값은 gsm, cdma, wcdma, lte, nr 이 필드는 선택사항이지만 라디오 유형이 확인할 수 있습니다
필드가 생략되면 Geolocation API가 기본적으로 gsm로 설정됩니다. 가정된 무선 유형이 오답입니다.
carrier string 이동통신사 이름입니다.
considerIp boolean WiFi 및 휴대폰 기지국 신호가 누락된 경우 IP 위치정보로 대체할지 여부를 지정합니다. 비어 있거나 기기 위치를 추정하기에 충분하지 않습니다. 기본값은 true입니다. 대체를 방지하려면 considerIpfalse로 설정합니다.
cellTowers array 휴대폰 기지국 객체의 배열입니다. 아래의 휴대폰 기지국 객체 섹션을 참고하세요.
wifiAccessPoints array WiFi 액세스 지점 객체의 배열입니다. Wi-Fi 액세스 포인트 객체 섹션을 참고하세요. 참조하세요.

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개 이상이 포함되어 있습니다. 기지국 객체입니다.

필드 JSON 유형 설명 참고
cellId number(uint32) 셀의 고유 식별자입니다. radioType gsm (기본값), cdma필수 wcdmalte nr에 대해 거부됨
아래의 cellId 계산 섹션에서 각 무선 유형에 유효한 값 범위.
newRadioCellId number(uint64) NR (5G) 셀의 고유 식별자입니다. radioType nr필수사항 거부됨(기타) 있습니다.
아래의 newRadioCellId 계산 섹션을 참고하세요. - 필드의 유효한 값 범위도 나열됩니다.
locationAreaCode number(uint32) GSM 및 WCDMA 네트워크용 LAC (위치 지역 코드)입니다.
CDMA 네트워크용 NID (Network ID)입니다.
LTE 및 NR 네트워크의 추적 지역 코드 (TAC)입니다.
radioType gsm (기본값)에 필수 cdma이며 다른 값의 경우에는 선택사항입니다.
gsm, cdma, wcdmalte: 0~65535.
nr의 유효 범위: 0~16777215
mobileCountryCode number(uint32) 휴대폰 기지국의 모바일 국가 코드 (MCC)입니다. radioType gsm (기본값), wcdma필수 ltenr cdma에 사용되지 않습니다.
유효 범위는 0~999입니다.
mobileNetworkCode number(uint32) 휴대폰 기지국의 모바일 네트워크 코드입니다. GSM, WCDMA, LTE, NR을 위한 MNC입니다.
CDMA는 시스템 ID (SID)를 사용합니다.
필수사항.
MNC의 유효 범위는 0~999입니다.
SID의 유효 범위는 0~32767입니다.

다음 선택 필드는 사용되지 않지만 값이 다음과 같은 경우 포함할 수 있습니다. 있습니다.

필드 JSON 유형 설명 참고
age number(uint32) 이 셀이 기본 셀이 된 이후의 밀리초 단위 시간입니다. 연령이 0이면 cellId 또는 newRadioCellId는 가장 적합합니다
signalStrength number(double) DBm 단위로 측정된 무선 신호 강도입니다.
timingAdvance number(double) 타이밍 어드밴스 값입니다.

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은(는) 필수 항목입니다. 모두 나머지 필드는 선택사항입니다.

필드 JSON 유형 설명 참고
macAddress string Wi-Fi 노드의 MAC 주소입니다. 일반적으로 BSS, BSSID 또는 MAC 주소라고 합니다. 필수.콜론으로 구분된 (:) 16진수 문자열입니다.
단독 범용으로 관리되는 MAC 주소는 API를 통해 찾을 수 있습니다. 다른 MAC 주소는 자동으로 삭제되어 API 요청이 비어 있습니다. 자세한 내용은 불필요한 Wi-Fi 액세스 중단을 참고하세요. 포인트가 있습니다.
signalStrength number(double) DBm 단위로 측정된 전류 신호 강도입니다. WiFi 액세스 포인트의 경우, dBm 값은 일반적으로 -35 이하이고 범위는 -128~-10dBm입니다. 이때 빼기 기호를 포함해야 합니다.
age number(uint32) 이 액세스 지점이 감지된 이후의 밀리초 단위 시간입니다.
channel number(uint32) 클라이언트가 액세스 지점과 통신 중인 채널입니다.
signalToNoiseRatio number(double) 전류 신호 대 잡음 비율 dB 단위로 측정됩니다

아래는 예시 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 주소는 이름이 macsmacAddress 문자열 배열:

자바
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")));
    
드림
<ph type="x-smartling-placeholder">
</ph>
Python
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')]
    
드림
<ph type="x-smartling-placeholder">
</ph>
JavaScript
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
}