Region Lookup API verwenden

Mit der Region Lookup API können Sie die Orts-IDs für Regionen abrufen. Die IDs lassen sich dann zum Gestalten von Begrenzungspolygonen mit datengestützten Stilen verwenden. Die Region Lookup API unterstützt zwei Arten von Anfragen:

Bei Region Lookup-Anfragen wird eine Region anhand des Ortsnamens, des FIPS-Codes (nur US-Bundesstaaten und ‑Countys) oder des ISO 3166-1-Ländercodes abgerufen.
Bei Region Search-Anfragen wird nach einer Region mit einem bestimmten Ort gesucht, der als Adresse, LatLng-Wert oder Orts-ID angegeben wird.

Unterstützte Ortstypen für Regionen

Die folgenden Ortstypen für Regionen werden unterstützt: country, administrative_area_level_1, administrative_area_level_2, postal_code, locality.

Bibliothek installieren

Um die Region Lookup API zu verwenden, sind folgende Schritte erforderlich:

Region Lookup API in der Console aktivieren
Open-Source-Bibliothek installieren: npm install @googlemaps/region-lookup

Abhängigkeiten aus der Bibliothek importieren

Die „Region Lookup“-Open-Source-Bibliothek bietet eine Reihe von Funktionen und TypeScript-Definitionen, die Sie in Ihren Code importieren müssen.

Importieren Sie für „Region Lookup“-Anfragen folgenden Code:

import {
  lookupRegion,
  LookupRegionRequestData,
  LookupRegionResponseData,
  LookupRegionResponse,
  RegionIdentifier
} from "@googlemaps/region-lookup";

Importieren Sie für „Region Search“-Anfragen folgenden Code:

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

„Region Lookup“-Anfragen

Bei „Region Lookup“-Anfragen wird für einen Ortsnamen oder Identifizierungscode eine Orts-ID zurückgegeben. Um eine Region nachzuschlagen, rufen Sie lookupRegion() auf und geben LookupRegionRequestData mit den folgenden Parametern an:

place oder unit_code (erforderlich): Entweder der Name der Region (place) oder der unit_code des Orts. Der unit_code kann entweder ein FIPS-Code (nur US-Bundesstaaten und ‑Countys) oder ISO 3166-1-Ländercode sein.
place_type (erforderlich): Der Wert für den Ortstyp des Orts, der nachgeschlagen werden soll.
region_code: Der zweistellige ISO 3166-Länder-/Regionscode für den Ort, der abgeglichen werden soll. region_code ist optional, wenn der „place_type“ COUNTRY ist.
language: Der BCP-47-Sprachcode, z. B. „en-US“ oder „sr-Latn“. Wenn keiner angegeben ist, wird standardmäßig „en-US“ verwendet.

Das folgende Beispiel zeigt eine „Region Lookup“-Anfrage für Newark, NJ, USA.

// 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 });

Der Parameter place oder unit_code ist erforderlich. Ist keiner von beiden definiert, wird ein Fehler zurückgegeben.

Der Parameter region_code ist erforderlich, außer place_type ist COUNTRY.

place und unit_code geben einen Ort an, mit dem eine Orts-ID abgeglichen werden soll. Wenn place beispielsweise „Kalifornien“ ist und place_type den Wert ADMINISTRATIVE_AREA_LEVEL_1 hat, gibt die API die Orts-ID für Kalifornien als matched_place_id zurück:

place_type: ADMINISTRATIVE_AREA_LEVEL_1

matched_place_id-Ergebnisse: Orts-ID für Kalifornien. Bei allen anderen unterstützten Typen wird keine Übereinstimmung zurückgegeben.

Wenn unit_code „6“ (FIPS-Code für Kalifornien) ist, place_type den Wert ADMINISTRATIVE_AREA_LEVEL_1 hat und region_code auf „US“ festgelegt ist, gibt die API die Orts-ID für Kalifornien zurück:

place_type: ADMINISTRATIVE_AREA_LEVEL_1
region_code: US

matched_place_id-Ergebnisse: Orts-ID für Kalifornien. Bei allen anderen unterstützten Typen wird keine Übereinstimmung zurückgegeben.

Ist unit_code „US“, gibt die API die folgenden Ergebnisse zurück, wenn folgende place_types angegeben sind:

place_type: COUNTRY

matched_place_id-Ergebnisse: Orts-ID für die USA. Bei allen anderen unterstützten Typen wird keine Übereinstimmung zurückgegeben.

Wenn keine Übereinstimmung gefunden wird, ist matched_place_id nicht festgelegt.

Wird kein eindeutiges Ergebnis gefunden, werden die möglichen Orts-IDs zurückgegeben. Wenn place z. B. „Santa Clara County“ ist und place_type den Wert LOCALITY hat, wird die Orts-ID für Santa Clara County als Möglichkeit zurückgegeben.

„Region Lookup“-Antwort

Wenn ein Ergebnis gefunden wurde, enthält das Objekt LookupRegionResponse eine matched_place_id. Wird kein Ergebnis gefunden, werden Orts-IDs mit geringerer Trefferwahrscheinlichkeit zusammen mit einem Fehlercode mit Debugging-Informationen als mögliche IDs zurückgegeben.

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

„Region Search“-Anfragen

Um eine Region mit einem bestimmten Ort zu suchen, rufen Sie searchRegion auf und geben dabei SearchRegionRequestData mit den folgenden Parametern an:

address, latlng oder place_id (erforderlich): Enthält entweder einen unstrukturierten Adressstring, einen latlng-Wert oder eine Orts-ID, der bzw. die zur Region gehören, z. B. einen POI oder ein Gebäude. Ist keiner der drei definiert, wird ein Fehler zurückgegeben.
place_type (erforderlich): Der Wert für den Ortstyp des Orts, der gesucht werden soll.
region_code: Der zweistellige ISO 3166-Länder-/Regionscode für den Ort, der abgeglichen werden soll. region_code ist erforderlich, wenn address angegeben ist.
language: Der BCP-47-Sprachcode, z. B. „en-US“ oder „sr-Latn“. Wenn keiner angegeben ist, wird standardmäßig „en-US“ verwendet.

Das folgende Beispiel zeigt eine „Region Search“-Anfrage für Burbank, CA, USA.

// 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 });

„Region Search“-Antwort

Wenn ein Ergebnis gefunden wurde, enthält das Objekt SearchRegionResponse eine matched_place_id. Wird keine Übereinstimmung gefunden, enthält die Antwort eine oder mehrere mögliche Orts-IDs und einen Fehlercode.

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

Referenz

`LookupRegionRequestData`-Kennungen

Feld	Typ	Beschreibung
`place`	String	Der Name der Region, die mit einer Orts-ID abgeglichen werden soll. Verwenden Sie das Feld `place` zusammen mit `place_type`, um die Orts-ID der Region zu ermitteln. Wenn `place_type` beispielsweise „locality“ ist, kann ein gültiger `place` „Palo Alto, CA“ sein. Wenn `place_type` „POSTAL_CODE“ ist, kann ein gültiger „place_name“ z. B. „94109“ sein. Wenn `place_type` COUNTRY ist, kann ein gültiger `place` z. B. USA sein. `region_code` ist erforderlich, wenn `place` angegeben ist, außer `place_type` ist COUNTRY.
`unit_code`	String	Der FIPS-Code für Bundesstaaten oder Countys (nur USA) oder ISO 3166-1-Ländercode, der abgeglichen werden soll. Das Feld `unit_code` wird zusammen mit `place_type` verwendet, um die Orts-ID der Region zu ermitteln. Wenn `place_type` z. B. `COUNTRY` ist, wären „US“ (ISO 3166-1 Alpha-2-Code für die USA) oder „BR“ (ISO 3166-1 Alpha-2-Code für Brasilien) gültige Werte für „unit_code“. Wenn `place_type` auf `ADMINISTRATIVE_AREA_LEVEL_1` (Bundesstaat) und „region_code“ auf „US“ gesetzt ist, wären „6“ (FIPS-Code für Kalifornien) oder „12“ (FIPS-Code für Florida) gültige Werte für „unit_code“. Wenn „place_type“ auf `ADMINISTRATIVE_AREA_LEVEL_2` (County) und „region_code“ auf „US“ gesetzt ist, wären „6001“ (FIPS-Code für Alameda County in Kalifornien) oder „12086“ (FIPS-Code für Miami-Dade County in Florida) gültige Werte für „unit_code“. `region_code` ist erforderlich, wenn ein FIPS-Code angegeben wird. `region_code` wird bei ISO 3166-1-Ländercodes ignoriert.
`place_type`	PlaceType	Erforderlich. Der Typ der Region, die abgeglichen werden soll.
`region_code`	String	Zweistelliger ISO 3166-Länder-/Regionscode für den Ort, den Sie abgleichen möchten. „region_code“ ist optional, wenn `place_type` COUNTRY ist.
`language_code`	String	Der BCP-47-Sprachcode, z. B. „en-US“ oder „sr-Latn“, für die Sprache, in der der Name und die Adresse des Orts angefordert werden. Wenn keiner angegeben ist, wird standardmäßig „en-US“ verwendet.

`SearchRegionRequestData`-Kennungen

ERFORDERLICH: Entweder address, latlng oder place_id.

Feld	Typ	Beschreibung
`address`	String	Eine unstrukturierte Adresse in einer Region, die abgeglichen werden soll. `region_code` ist erforderlich, wenn `address` angegeben ist.
`latlng`	LatLng	Ein Breiten- und Längengrad in einer Region, die abgeglichen werden soll.
`place_id`	String	Eine Orts-ID in einer Region, die abgeglichen werden soll.
`place_type`	Ortstyp	Erforderlich. Der Typ der Region, die abgeglichen werden soll.
`language_code`	String	Der BCP-47-Sprachcode, z. B. „en-US“ oder „sr-Latn“, für die Sprache, in der der Name und die Adresse des Orts angefordert werden. Wenn keiner angegeben ist, wird standardmäßig „en-US“ verwendet.
`region_code`	String	Der zweistellige ISO 3166-Länder-/Regionscode für den Ort, der abgeglichen werden soll. `region_code` ist erforderlich, wenn „address“ angegeben ist.

Ortstypen

Wert	Beschreibung
`POSTAL_CODE`	Eine Postleitzahl, wie sie zum Adressieren von Postsendungen innerhalb des Landes verwendet wird.
`ADMINISTRATIVE_AREA_LEVEL_1`	Eine öffentliche Verwaltungseinheit eine Stufe unterhalb der Landesebene. In den USA sind das die Bundesstaaten.
`ADMINISTRATIVE_AREA_LEVEL_2`	Eine öffentliche Verwaltungseinheit zwei Stufen unterhalb der Landesebene. In den USA sind das die Countys.
`LOCALITY`	Eine politische Einheit in Form einer Stadt oder Gemeinde.
`COUNTRY`	Die nationale Verwaltungseinheit, in der Regel die höchste in der Reihenfolge.

LatLng

Ein Objekt, das ein Paar aus Breiten- und Längengrad darstellt. Es wird als Paar zweier Werte (Breiten- und Längengrad) ausgedrückt. Sofern nicht anders angegeben, muss es World Geodetic System 1984 (WGS 84) entsprechen. Die Werte müssen innerhalb normalisierter Bereiche liegen.

Feld	Typ	Beschreibung
`latitude`	Doppelwert	Der Breitengrad in Grad. Er muss im Bereich `[-90.0, +90.0]` liegen, z. B. `47.47583476464538`.
`longitude`	Doppelwert	Der Längengrad in Grad. Er muss im Bereich `[-180.0, +180.0]` liegen, z. B. `-121.73858779269906`.

Fehlercodes

Wert	Beschreibung
`UnknownError`	Ein unbekannter Fehler ist aufgetreten.
`NoMatchFound`	Es wurde keine Übereinstimmung gefunden. Sehen Sie sich die `candidate_place_ids` an, sofern verfügbar.
`AddressNotUnderstood`	Die angegebene Adresse konnte nicht geocodiert werden.
`PlaceTypeMismatch`	Der Ortstyp in der Antwort stimmt nicht mit dem in der Anfrage überein. Das ist z. B. der Fall, wenn `locality` angefordert, aber `administrative_area_level_2` zurückgegeben wurde.
`MultipleCandidatesFound`	Für die Eingabe wurden mehrere mögliche Übereinstimmungen gefunden. Sehen Sie sich die `candidate_place_ids` an, sofern verfügbar.
`PlaceNameNotUnderstood`	Der angegebene Ortsname konnte nicht in eine Region aufgelöst werden.
`UnitCodeNotFound`	Der Einheitencode wurde nicht gefunden. Prüfen Sie, ob der Einheitencode gültig und im richtigen Format angegeben ist.
`PlaceTypeNotAllowed`	Die Orts-ID im Ergebnis steht nicht auf der Zulassungsliste für den Ortstyp und das Land.