Region Lookup API 사용

Region Lookup API를 사용하면 지역의 장소 ID를 찾을 수 있으며, 이를 사용하여 경계를 위한 데이터 기반 스타일 지정에서 경계 다각형의 스타일을 지정할 수 있습니다. Region Lookup API는 다음 두 종류의 요청을 지원합니다.

  • 지역 조회는 장소 이름, FIPS 코드(미국 주 및 카운티만 해당) 또는 ISO-3166-1 국가 코드로 지역을 조회합니다.
  • 지역 검색은 주소, LatLng 또는 장소 ID로 특정 위치가 포함된 지역을 검색합니다.

지원되는 지역 장소 유형

다음과 같은 지역 장소 유형이 지원됩니다: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality

라이브러리 설치

Region Lookup API를 사용하려면 다음 단계를 따르세요.

  1. 콘솔에서 Region Lookup API를 사용 설정합니다.
  2. 오픈소스 라이브러리를 설치합니다. npm install @googlemaps/region-lookup

라이브러리에서 종속 항목 가져오기

Region Lookup 오픈소스 라이브러리는 코드로 가져와야 하는 함수 및 TypeScript 입력을 제공합니다.

  • 지역 조회 요청의 경우 다음을 가져옵니다.

    import {
      lookupRegion,
      LookupRegionRequestData,
      LookupRegionResponseData,
      LookupRegionResponse,
      RegionIdentifier
    } from "@googlemaps/region-lookup";
    
  • 지역 검색 요청의 경우 다음을 가져옵니다.

    import {
      searchRegion,
      RegionSearchValue,
      SearchRegionRequestData,
      SearchRegionResponse
    } from "@googlemaps/region-lookup";
    

지역 조회 요청

지역 조회 요청은 장소 이름 또는 식별자 코드를 가져와서 장소 ID를 반환합니다. 지역을 조회하려면 lookupRegion()을 호출하고 다음 매개변수를 사용하여 LookupRegionRequestData를 지정하세요.

  • place 또는 unit_code(필수) - 장소의 지역 이름(place) 또는 unit_code. unit_code는 FIPS 코드(미국 주 및 카운티만 해당) 또는 ISO-3166-1 국가 코드입니다.
  • place_type(필수) - 조회할 장소 유형의 장소 유형
  • region_code - 일치시킬 위치의 두 자리 ISO-3166 국가/지역 코드. place_type이 COUNTRY인 경우 region_code는 선택사항입니다.
  • language - BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn'). 지정되지 않은 경우 기본값은 en-US입니다.

다음 예는 뉴저지주 뉴어크에 대한 조회 요청을 보여줍니다.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};
const data: LookupRegionRequestData = {
  identifiers: [
    {
      "place": "newark",
      "place_type": "locality",
      "region_code": "us",
      "language": "en",
    },
  ],
};
const response: LookupRegionResponse = await RegionLookup.lookupRegion({ headers, data });

place 또는 unit_code 매개변수가 필요합니다. 지정하지 않으면 오류가 반환됩니다.

place_typeCOUNTRY가 아니면 region_code 매개변수가 필요합니다.

placeunit_code는 장소 ID를 일치시킬 위치를 지정합니다. 예를 들어 place가 'California'이고 place_typeADMINISTRATIVE_AREA_LEVEL_1이면 API는 캘리포니아의 장소 ID를 matched_place_id로 반환합니다.

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1

    matched_place_id 결과: 캘리포니아의 장소 ID. 기타 지원되는 모든 유형은 일치하는 항목을 반환하지 않습니다.

unit_code가 '6'(캘리포니아의 FIPS 코드), place_typeADMINISTRATIVE_AREA_LEVEL_1, region_code가 'US'인 경우 API는 캘리포니아의 장소 ID를 반환합니다.

  • place_type: ADMINISTRATIVE_AREA_LEVEL_1
  • region_code: US

    matched_place_id 결과: 캘리포니아의 장소 ID. 기타 지원되는 모든 유형은 일치하는 항목을 반환하지 않습니다.

unit_code가 'US'이면 다음 place_type이 지정된 경우 API는 다음 결과를 반환합니다.

  • place_type: COUNTRY

    matched_place_id 결과: 미국의 장소 ID. 기타 지원되는 모든 유형은 일치하는 항목을 반환하지 않습니다.

일치하는 항목이 없으면 matched_place_id가 설정되지 않습니다.

모호한 경우에는 후보 장소 ID가 반환됩니다. 예를 들어 place가 '산타클라라 카운티'이고 place_typeLOCALITY이면 산타클라라 카운티의 장소 ID가 후보로 반환됩니다.

지역 조회 응답

결과가 발견되면 LookupRegionResponse 객체에 matched_place_id가 포함됩니다. 결과가 발견되지 않으면 신뢰도가 낮은 장소 ID가 디버깅 정보가 포함된 오류 코드와 함께 후보 ID로 반환됩니다.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

지역 검색 요청

특정 위치가 포함된 지역을 찾으려면 searchRegion을 호출하고 다음 매개변수를 사용하여 SearchRegionRequestData를 지정하세요.

  • address, latlng 또는 place_id(필수) - 지역에 의해 포함된 구조화되지 않은 주소 문자열 latlng 또는 장소 ID(예: 관심 장소, 건물 등)를 포함함. 지정하지 않으면 오류가 반환됩니다.
  • place_type(필수) - 검색할 지역 유형의 장소 유형
  • region_code - 일치시킬 위치의 두 자리 ISO-3166 국가/지역 코드. address가 지정된 경우 region_code가 필요합니다.
  • language - BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn'). 지정되지 않은 경우 기본값은 en-US입니다.

다음 예는 캘리포니아주 버뱅크에 대한 조회 요청을 보여줍니다.

// Headers
const headers = {
  "X-Goog-Api-Key": "YOUR API KEY",
};

const data: SearchRegionRequestData = {
  search_values: [
    {
      "address": "2627 N Hollywood Way, Burbank, CA" ,
      "place_type": "locality" as const,
      "region_code": "us"
    },
  ],
};
const response = await regionLookupClient.searchRegion({ headers, data });

지역 검색 응답

결과가 발견되면 SearchRegionResponse 객체에 matched_place_id가 포함됩니다. 일치하는 항목을 찾지 못한 경우에는 응답에 하나 이상의 후보 장소 ID와 오류 코드가 포함됩니다.

{
  "matches": [
    {
      "matchedPlaceId": "ChIJPV4oX_65j4ARVW8IJ6IJUYs"
    }
  ]
}

참조

LookupRegionRequestData 식별자

필드 유형 설명
place 문자열 장소 ID와 일치시킬 지역의 이름입니다. 지역 장소 ID를 조회하려면 place 필드를 place_type과 함께 사용하세요. 예를 들어 place_type이 'locality'인 경우 유효한 place는 'Palo Alto, CA'일 수 있습니다. place_type이 'POSTAL_CODE'인 경우 유효한 place_name은 '94109'일 수 있습니다. place_type이 'COUNTRY'인 경우 유효한 place는 '미국' 등일 수 있습니다. place_type이 'COUNTRY'가 아닌 경우 place가 지정되면 region_code가 필요합니다.
unit_code 문자열 일치시킬 FIP 주 또는 카운티 코드(미국만 해당) 또는 ISO-3166-1 국가 코드입니다. unit_code 필드는 지역 장소 ID를 조회하기 위해 place_type과 함께 사용됩니다. 예를 들어 place_typeCOUNTRY인 경우 유효한 unit_code는 'US'(미국의 ISO-3166-1 Alpha-2 코드) 또는 'BR'(브라질의 ISO-3166-1 Alpha-2 코드)일 수 있습니다. place_typeADMINISTRATIVE_AREA_LEVEL_1(주)이고 region_code가 'US'인 경우 유효한 unit_code는 '6'(캘리포니아의 FIP 코드) 또는 '12'(플로리다의 FIP 코드)일 수 있습니다. place_type이 ADMINISTRATIVE_AREA_LEVEL_2(카운티)이고 region_code가 'US'인 경우 유효한 unit_code는 '6001'(캘리포니아주 앨러미다 카운티의 FIP 코드) 또는 '12086'(플로리다주 마이애미데이드 카운티의 FIP 코드)일 수 있습니다. region_code는 FIP 코드를 지정할 때 필요합니다. ISO-3166-1 국가 코드의 경우 region_code가 무시됩니다.
place_type PlaceType 필수입니다. 일치시킬 지역의 유형입니다.
region_code 문자열 일치시키려고 하는 위치의 두 자리 ISO-3166 국가/지역 코드입니다. place_type이 'COUNTRY'인 경우 region_code는 선택사항입니다.
language_code 문자열 BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn')로 장소 이름과 주소가 요청된 언어에 해당합니다. 아무것도 요청되지 않은 경우 기본적으로 영어가 사용됩니다.

SearchRegionRequestData 식별자

필수: address, latlng, place_id 중 하나입니다.

필드 유형 설명
address 문자열 일치시킬 지역 내에 포함된 구조화되지 않은 상세 주소입니다. address가 지정된 경우 region_code가 필요합니다.
latlng LatLng 일치시킬 지역 내에 포함된 위도와 경도입니다.
place_id 문자열 일치시킬 지역 내에 포함된 장소 ID입니다.
place_type place type 필수입니다. 일치시킬 지역의 유형입니다.
language_code 문자열 BCP-47 언어 코드(예: 'en-US' 또는 'sr-Latn')로 장소 이름과 주소가 요청된 언어에 해당합니다. 아무것도 요청되지 않은 경우 기본적으로 영어가 사용됩니다.
region_code 문자열 일치시킬 위치의 두 자리 ISO-3166 국가/지역 코드입니다. 주소가 지정된 경우 region_code가 필요합니다.

장소 유형

설명
POSTAL_CODE 국가 내에서 우편물을 보낼 때 사용되는 우편번호입니다.
ADMINISTRATIVE_AREA_LEVEL_1 국가 수준 아래 첫 번째 행정 독립체입니다. 미국에서 이 행정 구역 수준은 주입니다.
ADMINISTRATIVE_AREA_LEVEL_2 국가 수준 아래 두 번째 행정 독립체입니다. 미국에서 이 행정 구역 수준은 카운티입니다.
LOCALITY 도시 또는 마을로 통합된 정치적 독립체입니다.
COUNTRY 전국적인 정치적 독립체로 일반적으로 순위가 가장 높은 유형입니다.

LatLng

위도/경도 쌍을 나타내는 객체로 위도(도)와 경도(도)를 나타내는 double의 쌍으로 표현됩니다. 달리 명시되지 않는 한 이 객체는 WGS84 표준을 준수해야 합니다. 값은 정규화된 범위 내에 있어야 합니다.

필드 유형 설명
latitude double 위도(도)입니다. 범위는 [-90.0, +90.0]이어야 합니다. 예: 47.47583476464538
longitude double 경도(도)입니다. 범위는 [-180.0, +180.0]이어야 합니다. 예: -121.73858779269906

오류 코드

설명
UnknownError 알 수 없는 오류가 발생했습니다.
NoMatchFound 요청에 일치하는 결과가 없습니다. 사용 가능한 경우 candidate_place_ids를 확인하세요.
AddressNotUnderstood 입력한 주소에 대해 지오코딩이 실패했습니다.
PlaceTypeMismatch 응답의 장소 유형이 요청의 장소 유형과 일치하지 않습니다. 예를 들어 locality가 요청되었지만 administrative_area_level_2가 반환되었습니다.
MultipleCandidatesFound 입력한 내용과 일치하는 항목이 여러 개 있습니다. 사용 가능한 경우 candidate_place_ids를 확인하세요.
PlaceNameNotUnderstood 제공된 장소 이름으로 지역을 확인할 수 없습니다.
UnitCodeNotFound 단위 코드를 찾을 수 없습니다. 단위 코드가 올바르고 올바른 형식으로 입력되었는지 확인하세요.
PlaceTypeNotAllowed 일치하는 장소 ID가 장소 유형 및 국가 허용 목록에 없습니다.