최근 사용

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

소개

Geolocation API는 모바일 클라이언트가 감지할 수 있는 휴대폰 기지국 및 Wi-Fi 노드에 대한 정보를 기반으로 위치 및 정확도 반경을 반환합니다. 이 문서에서는 이 데이터를 서버로 전송하고 클라이언트에 응답을 반환하는 데 사용되는 프로토콜을 설명합니다.

통신은 POST를 사용하여 HTTPS를 통해 수행됩니다. 요청 및 응답의 형식은 모두 JSON이며, 두 콘텐츠 유형은 application/json입니다.

시작하기 전에

Geolocation API로 개발을 시작하기 전에 인증 요구사항(API 키 필요) 및 API 사용 및 결제 정보 (프로젝트에서 결제를 사용 설정해야 함)를 검토합니다.

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)입니다. radioTypegsm(기본값), 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 유형 설명 메모
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)입니다. radioTypegsm(기본값), 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) 이전의 무선 유형은 네트워크 셀 ID를 Geolocation API에 전달하기 위해 32비트 cellId 필드를 사용합니다.

  • GSM (2G) 네트워크는 16비트 셀 ID (CID)를 있는 그대로 사용합니다. 유효한 범위는 0~65535입니다.
  • CDMA (2G) 네트워크는 16비트 기본 스테이션 ID (BID)를 있는 그대로 사용합니다. 유효한 범위는 0~65535입니다.
  • WCDMA (3G) 네트워크는 UTRAN/GERAN 셀 ID (UC-ID)를 사용합니다. UC-ID는 12비트 무선 네트워크 컨트롤러 식별자 (RNC-ID)와 16비트 셀 ID (CID)를 연결하는 28비트 정수 값입니다.
    수식: rnc_id << 16 | cid
    유효 범위: 0~268435455.
    참고: WCDMA 네트워크에서 16비트 셀 ID 값만 지정하면 결과가 부정확하거나 0개가 됩니다.
  • LTE(4G) 네트워크는 20비트 정수 값인 E-UTRAN 셀 ID(ECI)를 사용합니다.
    수식: enb_id << 8 | cid
    유효 범위: 0~268435455.
    참고: LTE 네트워크에서 8비트 셀 ID 값만 지정하면 결과가 잘못되었거나 0이 됩니다.

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

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

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

newRadioCellId 계산 중

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

  • NR (5G) 네트워크는 36비트 신규 무선 셀 ID (NCI)를 그대로 사용합니다.
    유효한 범위: 0~68719476735

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

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

WiFi 액세스 지점 객체

요청 본문의 wifiAccessPoints 배열에 둘 이상의 Wi-Fi 액세스 포인트 객체가 포함되어야 합니다. macAddress는 필수이며 다른 모든 필드는 선택사항입니다.

필드 JSON 유형 설명 메모
macAddress string Wi-Fi 노드의 MAC 주소입니다. 일반적으로 BSS, BSSID 또는 MAC 주소입니다. 필수사항. : (콜론) 구분 16진수 문자열
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 응답

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

  • location: 사용자의 예상 위도 및 경도입니다(도 단위). 1개의 lat 및 1개의 lng 하위 필드를 포함합니다.
  • accuracy: 추정 위치의 정확도(미터 단위)입니다. 주어진 location 주변의 원의 반경을 나타냅니다.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

오류

오류가 발생하면 표준 형식 오류 응답 본문이 반환되고 HTTP 상태 코드가 오류 상태로 설정됩니다.

응답에는 다음 키와 함께 단일 error 객체가 있는 객체가 포함됩니다.

  • code: 응답의 HTTP 상태와 동일합니다.
  • message: 오류에 대한 간단한 설명입니다.
  • errors: 발생한 오류 목록입니다. 각 오류에는 오류 유형의 식별자 (reason) 및 간단한 설명(message)이 포함됩니다.

예를 들어, 잘못된 JSON을 전송하면 다음과 같은 오류가 반환됩니다.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

가능한 오류는 다음과 같습니다.

이유 도메인 HTTP 상태 코드 설명
dailyLimitExceeded usageLimits 403 일일 한도를 초과했습니다.
keyInvalid usageLimits 400 API 키가 Geolocation API에 유효하지 않습니다. 전체 키를 포함했는지, API를 구매했는지 또는 결제를 사용 설정하고 API를 활성화하여 할당량을 무료로 받았는지 확인하세요.
userRateLimitExceeded usageLimits 403 Google Cloud Console에서 구성한 요청 한도를 초과했습니다. 이 한도는 일반적으로 일일 요청 수, 100초당 요청 수, 사용자당 100초당 요청으로 설정됩니다. 단일 또는 소규모 사용자 그룹이 일일 할당량을 소진하지 못하게 하는 동시에 모든 사용자에게 합리적인 액세스 권한을 허용하려면 이 한도를 구성해야 합니다. 이러한 한도를 구성하려면 API 사용량 한도를 참조하세요.
notFound geolocation 404 요청이 올바르지만 결과가 반환되지 않았습니다.
parseError global 400 요청 본문이 올바른 JSON이 아닙니다. 각 필드에 대한 자세한 내용은 요청 본문 섹션을 참조하세요.

샘플 요청

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

(API 키가 없는 경우 API 키 가져오기를 참고하세요.)

추가 테스트를 위해 Android용 Places SDK 및 Android Location API를 사용하여 Android 기기에서 정보를 수집하고 iOS용 Places SDK를 사용하여 iOS 기기에서 정보를 수집할 수 있습니다.

자주 묻는 질문(FAQ)

Geolocation 응답에서 accuracy 반경이 매우 큰 이유는 무엇인가요?

Geolocation 응답에서 accuracy 필드에 매우 높은 값이 표시되면 Wi-Fi 포인트나 휴대폰 기지국 대신 요청 IP를 기반으로 위치정보가 파악될 수 있습니다. 휴대폰 기지국이나 액세스 포인트가 유효하거나 인식되지 않는 경우에 이러한 상황이 발생할 수 있습니다.

문제인지 확인하려면 요청에서 considerIp를 false로 설정하세요. 응답이 404인 경우 wifiAccessPoints 및 cellTowers 객체의 위치정보를 찾을 수 없는 것입니다.