이 페이지는 Cloud Translation API를 통해 번역되었습니다.

위치정보 요청 및 응답

Geolocation 요청

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

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

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

요청 본문

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

필드	JSON 유형	설명	Notes
`homeMobileCountryCode`	`number`(`uint32`)	기기의 홈 네트워크에 대한 모바일 국가 코드 (MCC)입니다.	`radioType` `gsm` (기본값), `wcdma`, `lte`, `nr`에 지원되며 `cdma`에는 사용되지 않습니다. 유효 범위는 0~999입니다.
`homeMobileNetworkCode`	`number`(`uint32`)	기기의 홈 네트워크의 모바일 네트워크 코드입니다. GSM, WCDMA, LTE, NR용 MNC입니다. CDMA는 시스템 ID (SID)를 사용합니다.	MNC의 유효 범위는 0~999입니다. SID의 유효한 범위는 0~32767입니다.
`radioType`	`string`	모바일 무선 유형입니다. 지원되는 값은 `gsm`, `cdma`, `wcdma`, `lte`, `nr`입니다.	이 필드는 선택사항이지만 클라이언트가 라디오 유형을 알고 있다면 항상 포함해야 합니다. 이 필드를 생략하면 Geolocation API의 기본값이 `gsm`로 설정됩니다. 따라서 가정된 라디오 유형이 잘못되면 무효하거나 0개의 결과가 발생합니다.
`carrier`	`string`	이동통신사 이름입니다.
`considerIp`	`boolean`	Wi-Fi 및 휴대폰 기지국 신호가 누락되거나 비어 있거나 기기 위치를 추정하기에 충분하지 않은 경우 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 유형	설명	Notes
`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 네트워크의 네트워크 ID (NID)입니다. 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 유형	설명	Notes
`age`	`number`(`uint32`)	이 셀이 기본 셀이 된 이후의 밀리초 단위 시간입니다.	연령이 0이면 `cellId` 또는 `newRadioCellId`는 현재 측정값을 나타냅니다.
`signalStrength`	`number`(`double`)	DBm 단위로 측정된 무선 신호 강도입니다.
`timingAdvance`	`number`(`double`)	타이밍 어드밴티지 값입니다.

`cellId` 계산 중

NR (5G) 이전의 라디오 유형은 네트워크 셀 ID를 Geolocation API에 전달하기 위해 32비트 cellId 필드를 사용합니다.

GSM (2G) 네트워크는 16비트 셀 ID (CID)를 있는 그대로 사용합니다. 유효한 범위는 0~65535입니다.
CDMA (2G) 네트워크는 16비트 기지국 ID (BID)를 그대로 사용합니다. 유효한 범위는 0~65535입니다.
WCDMA (3G) 네트워크는 12비트 무선 네트워크 컨트롤러 식별자 (RNC-ID)와 16비트 셀 ID (CID)를 연결하는 28비트 정수 값인 UC-ID (UTRAN/GERAN Cell Identity)를 사용합니다.
수식: 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
    }
  ]
}

`newRadioCellId` 계산 중

셀 ID가 32비트보다 긴 최신 네트워크는 64비트 newRadioCellId 필드를 사용하여 네트워크 셀 ID를 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 배열에는 Wi-Fi 액세스 포인트 객체가 두 개 이상 포함되어야 합니다. macAddress은 필수이며 다른 모든 필드는 선택사항입니다.

필드	JSON 유형	설명	Notes
`macAddress`	`string`	WiFi 노드의 MAC 주소입니다. 일반적으로 BSS, BSSID 또는 MAC 주소라고 합니다.	필수.콜론으로 구분된 (`:`) 16진수 문자열입니다. API를 통해 범용 관리 MAC 주소만 찾을 수 있습니다. 다른 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": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

사용하지 않는 Wi-Fi 액세스 포인트 중단

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

로컬에서 관리되는 MAC 주소는 API에 유용한 위치 신호가 아니며 요청에서 자동으로 삭제됩니다. 이러한 MAC 주소는 macAddress의 최상위 바이트에서 두 번째 최하위 비트가 0인지 확인하여 삭제할 수 있습니다(예: 02:00:00:00:00:00의 2로 표시되는 1비트). 브로드캐스트 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")));

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

자바스크립트

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
}