새로운 지도 스타일이 곧 Google Maps Platform에 제공될 예정입니다. 이 지도 스타일 지정 업데이트에는 새로운 기본 색상 팔레트와 지도 환경 및 사용성 개선사항이 포함됩니다. 모든 지도 스타일이 2025년 3월에 자동으로 업데이트됩니다. 사용 가능 여부 및 더 일찍 선택하는 방법에 대한 자세한 내용은 Google Maps Platform용 새로운 지도 스타일을 참고하세요.

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를 사용하려면 다음 단계를 따르세요.

콘솔에서 Region Lookup API를 사용 설정합니다.
오픈소스 라이브러리를 설치합니다. 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_type이 COUNTRY가 아니면 region_code 매개변수가 필요합니다.

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

place_type: ADMINISTRATIVE_AREA_LEVEL_1

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

unit_code가 '6'(캘리포니아의 FIPS 코드), place_type이 ADMINISTRATIVE_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_type이 LOCALITY이면 산타클라라 카운티의 장소 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_type`이 `COUNTRY`인 경우 유효한 unit_code는 'US'(미국의 ISO-3166-1 Alpha-2 코드) 또는 'BR'(브라질의 ISO-3166-1 Alpha-2 코드)일 수 있습니다. `place_type`이 `ADMINISTRATIVE_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가 장소 유형 및 국가 허용 목록에 없습니다.