모든 준비를 마쳤습니다!

개발을 시작하려면 개발자 문서로 이동하세요.

Google Maps Geolocation API 활성화

개발을 시작하기 위해 Google Developers Console에서 우선적으로 해야 할 일을 몇 가지 소개하겠습니다.

  1. 프로젝트 생성 또는 선택
  2. Google Maps Geolocation API 활성화
  3. 적합한 키 생성
계속

Google Maps Geolocation API

개요

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

통신은 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 형식으로 지정되어야 합니다. 다음과 같은 필드가 지원되며, 모든 필드는 선택 항목입니다.

  • homeMobileCountryCode: 기기의 홈 네트워크에 대한 모바일 국가 코드(MCC).
  • homeMobileNetworkCode: 기기의 홈 네트워크에 대한 모바일 네트워크 코드(MNC).
  • radioType: 모바일 무선 유형. 지원되는 값은 lte, gsm, cdmawcdma입니다. 이 필드는 선택 항목이지만, 값이 있는 경우에는 보다 정확한 결과를 위해 이 필드를 포함해야 합니다.
  • carrier: 이동통신사 이름.
  • considerIp: WiFi 및 휴대폰 기지국 신호를 사용할 수 없는 경우, IP Geolocation으로 돌아갈지 여부를 지정합니다. 참고로, 요청 헤더에 있는 IP 주소가 기기의 IP가 아닐 수도 있습니다. 기본값은 true입니다. 돌아가지 않으려면 considerIpfalse로 설정합니다.
  • cellTowers: 휴대폰 기지국 객체의 배열. 아래의 휴대폰 기지국 객체 섹션을 참조하세요.
  • wifiAccessPoints: WiFi 액세스 지점 객체의 배열. 아래의 WiFi 액세스 지점 객체 섹션을 참조하세요.
{
  "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개 이상의 휴대폰 기지국 객체가 포함됩니다.

  • cellId(필수): 셀의 고유 식별자. GSM에서 이 식별자는 CID(Cell ID)이며, CDMA 네트워크에서는 BID(Base Station ID)를 사용합니다. WCDMA 네트워크에서는 RNC(Radio Network Controller)와 Cell ID를 연결한 32비트 값인 UC-ID(UTRAN/GERAN Cell Identity)를 사용합니다. WCDMA 네트워크에서 16비트 Cell ID 값만 지정하면 부정확한 결과가 반환될 수 있습니다.
  • locationAreaCode(필수): GSM 및 WCDMA 네트워크용 LAC(Location Area Code). CDMA 네트워크용 NID(Network ID).
  • mobileCountryCode(필수): 휴대폰 기지국의 모바일 국가 코드(MCC).
  • mobileNetworkCode(필수): 휴대폰 기지국의 모바일 네트워크 코드. 이 코드는 GSM 및 WCDMA용 MNC이며, CDMA는 SID(System ID)를 사용합니다.

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

  • age: 이 셀이 기본 셀이 된 이후의 밀리초 단위 시간. 이 값이 0이면, cellId는 현재 측정값을 나타냅니다.
  • signalStrength: DBm 단위로 측정된 무선 신호 강도.
  • timingAdvance: 타이밍 어드밴스 값.

아래는 예시 GSM 휴대폰 기지국 객체입니다.

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

아래는 예시 WCDMA 휴대폰 기지국 객체입니다.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

WiFi 액세스 지점 객체

요청 본문의 wifiAccessPoints 배열에는 둘 이상의 WiFi 액세스 지점 객체가 포함되어야 합니다. macAddress는 필수이며, 다른 모든 필드는 선택 항목입니다.

  • macAddress:(필수) WiFi 노드의 MAC 주소. 구분 기호는 :(콜론)이어야 합니다.
  • signalStrength: DBm 단위로 측정된 전류 신호 강도.
  • age: 이 액세스 지점이 감지된 이후의 밀리초 단위 시간.
  • channel: 클라이언트가 액세스 지점과 통신 중인 채널.
  • signalToNoiseRatio: dB 단위로 측정된 전류 신호 대 잡음 비.

아래는 예시 WiFi 액세스 지점 객체입니다.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Geolocation 응답

성공적인 Geolocation 요청은 위치 및 반경을 정의하는 JSON 형식의 응답을 반환합니다.

  • location: 사용자의 예상 위도 및 경도(도 단위). 하나의 lat와 하나의 lng 하위 필드를 포함합니다.
  • accuracy: 예상 위치의 정확도(미터 단위). 이 값은 지정된 location 주변의 반경을 나타냅니다.
{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

오류

오류의 경우, 표준 형식의 오류 응답 본문이 반환되고 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 Google Maps Geolocation API의 API 키가 올바르지 않습니다. 전체 키가 포함되었는지 확인하고, 무료 할당량을 얻기 위해 API를 구매했는지 또는 결제를 사용하고 API를 활성화했는지 확인하세요.
userRateLimitExceeded usageLimits 403 Google API Console에서 구성한 사용자별 초당 요청 제한을 초과했습니다. 단일 사용자 또는 소규모 사용자 그룹이 귀하의 일일 할당량을 소진하지 못하게 하는 동시에, 모든 사용자에게 적절한 액세스를 허용하려면 이 제한을 구성해야 합니다.
notFound geolocation 404 요청이 올바르지만 결과가 반환되지 않았습니다.
parseError global 400 요청 본문이 올바른 JSON이 아닙니다. 각 필드에 대한 자세한 내용은 요청 본문 섹션을 참조하세요.

샘플 요청

샘플 데이터로 Google Maps Geolocation API를 사용해 보고 싶으면, 다음과 같은 JSON을 파일에 저장합니다.

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "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": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

(API 키가 없으면 키 가져오기를 참조하세요.)

추가 테스트를 위해 Android 기기는 Google Places API for AndroidAndroid Location API를 사용하여 정보를 수집하고, iOS 기기는 Google Places API for iOS를 사용하여 정보를 수집할 수 있습니다.

질문과 대답(FAQ)

내 Geolocation 응답에서 accuracy 반경이 매우 큰 이유가 무엇입니까?

Geolocation 응답에서 accuracy 필드의 값이 매우 크게 표시된다면, WiFi 지점 또는 휴대폰 기지국 대신에 요청 IP를 기준으로 Geolocation이 수행 중일 수도 있습니다. 휴대폰 기지국 또는 액세스 지점이 올바르지 않거나 인식되지 않으면 이러한 문제가 발생할 수 있습니다.

문제가 이 경우에 해당하는지 확인하려면, 요청에서 considerIpfalse로 설정하세요. 응답이 404이면, wifiAccessPointscellTowers 객체에 대해 Geolocation을 수행할 수 없는 것으로 확인된 상태입니다.

다음에 대한 의견 보내기...

Google Maps Geolocation API
Google Maps Geolocation API
도움이 필요하시나요? 지원 페이지를 방문하세요.