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 für Grenzen 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 anhand eines bestimmten Orts 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:

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

Abhängigkeiten aus der Bibliothek importieren

Die Open-Source-Bibliothek „Region Lookup“ bietet eine Reihe von Funktionen und TypeScript-Typisierungen, 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 Sie 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 ein ISO-3166-1-Ländercode sein.
  • place_type (erforderlich): Der Wert für den Ortstyp des Orts, der nachgeschlagen werden soll.
  • region_code: Der passende zweistellige ISO-3166-Länder-/Regionscode für den Ort. 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, dem eine Orts-ID passend zugeordnet 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_type-Werte 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, wird 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 Sie 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 passende zweistellige ISO-3166-Länder-/Regionscode für den Ort. 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 einer Orts-ID als passend zugeordnet 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 wurde, 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, dem die passende Orts-ID zugeordnet 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 gültige Werte für „unit_code“ z. B. „US“ (ISO-3166-1-Alpha-2-Code für die USA) oder „BR“ (ISO-3166-1-Alpha-2-Code für Brasilien). Wenn place_type auf ADMINISTRATIVE_AREA_LEVEL_1 (Bundesstaat) und „region_code“ auf „US“ gesetzt ist, wären z. B. „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 z. B. „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 als passend zugeordnet werden soll.
region_code String Zweistelliger ISO-3166-Länder-/Regionscode für den Ort, der als passend zugeordnet werden soll. „region_code“ ist optional, wenn place_type mit „COUNTRY“ definiert 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 als passend zugeordnet werden soll. region_code ist erforderlich, wenn address angegeben ist.
latlng LatLng Ein Breiten- und Längengrad in einer Region, die als passend zugeordnet werden soll.
place_id String Eine Orts-ID innerhalb einer Region, die als passend zugeordnet werden soll.
place_type Ortstyp Erforderlich. Der Typ der Region, die als passend zugeordnet 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 als passend zugeordnet 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 dies die Bundesstaaten.
ADMINISTRATIVE_AREA_LEVEL_2 Eine öffentliche Verwaltungseinheit zwei Stufen unterhalb der Landesebene. In den USA sind dies die Countys.
LOCALITY Eine politische Einheit in Form einer Stadt oder Gemeinde.
COUNTRY Die nationale Verwaltungseinheit, in der Regel die der höchsten Ebene.

LatLng

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

Feld Typ Beschreibung
latitude Double Der Breitengrad in Grad. Er muss im Bereich [-90.0, +90.0] liegen, z. B. 47.47583476464538.
longitude Double 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.