위치정보 요청 및 응답

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입니다. considerIp 설정값 false: 대체를 방지합니다.
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에 필수 wcdma 및 lte 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, wcdma 및 lte: 0~65535. nr가 있는 유효 범위: 0~16777215
mobileCountryCode	number(uint32)	휴대폰 기지국의 모바일 국가 코드 (MCC)입니다.	radioType gsm (기본값), wcdma에 필수 lte 및 nr 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) 네트워크는 28비트 정수인 UTRAN/GERAN Cell Identity (UC-ID)를 사용합니다. 12비트 무선 네트워크 컨트롤러 식별자 (RNC-ID)와 16비트를 연결하는 값 셀 ID (CID).
  수식: 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
}

샘플 요청

참고: Mac 주소는 시간이 지남에 따라 변경될 수 있습니다. 따라서 이 페이지의 예시를 실행하면 오류 메시지가 표시될 수 있습니다. 가져올 수 있습니다.

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 호출의 성공률을 높일 수 있습니다. 필터링 후 Geolocation API 호출이 이전 위치 신호 또는 WiFi 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 문자열 배열:

<ph type="x-smartling-placeholder">

</ph>

자바

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")));
    

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')]
    

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
}