Search - Get Geocoding

Verwenden Sie diese Option, um die Längen- und Breitengradkoordinaten einer Straßenadresse oder den Namen eines Ortes abzurufen.
Bei der Get Geocoding API handelt es sich um eine HTTP-Anforderung GET , die die Längen- und Breitengradkoordinaten des gesuchten Standorts zurückgibt.

In vielen Fällen ist der vollständige Suchdienst möglicherweise zu viel, z. B. wenn Sie nur an herkömmlicher Geocodierung interessiert sind. Auf die Suche kann auch ausschließlich nach Adressen zugegriffen werden. Die Geokodierung erfolgt durch Klicken auf den Geokodierungsendpunkt nur mit der betreffenden Adresse oder Teiladresse. Der Geocodierungssuchindex wird für alles über den Daten auf Straßenebene abgefragt. Es werden keine Points of Interest (POIs) zurückgegeben. Beachten Sie, dass der Geocoder sehr tolerant von Tippfehlern und unvollständigen Adressen ist. Es wird auch alles verarbeiten, von genauen Straßenadressen oder Straßen oder Kreuzungen bis hin zu übergeordneten Regionen wie Stadtzentren, Landkreisen und Bundesländern. Die Antwort gibt auch detaillierte Adresseigenschaften wie Straße, Postleitzahl, Gemeinde und Länder-/Regionsinformationen zurück.

GET {endpoint}/geocode?api-version=2026-01-01

GET {endpoint}/geocode?api-version=2026-01-01&top={top}&query={query}&addressLine={addressLine}&countryRegion={countryRegion}&bbox={bbox}&view={view}&coordinates={coordinates}&adminDistrict={adminDistrict}&adminDistrict2={adminDistrict2}&adminDistrict3={adminDistrict3}&locality={locality}&postalCode={postalCode}

URI-Parameter

Anforderungsheader

Antworten

Sicherheit

AadToken

Dies sind die Microsoft Entra OAuth 2.0 Flows. In Kombination mit Azure rollenbasierten Zugriffs Steuerung kann sie verwendet werden, um den Zugriff auf Azure Maps REST-APIs zu steuern. Azure-rollenbasierte Zugriffskontrollen werden verwendet, um den Zugriff auf ein oder mehrere Azure Maps-Ressourcenkonten oder -Unterressourcen zu bestimmen. Jedem Benutzer, Gruppen- oder Dienstprinzipal kann über eine integrierte Rolle oder eine benutzerdefinierte Rolle, die aus einer oder mehreren Berechtigungen für Azure Maps-REST-APIs besteht, Zugriff gewährt werden.

Um Szenarien zu implementieren, empfehlen wir, Authentifizierungskonzepteanzuzeigen. Zusammenfassend bietet diese Sicherheitsdefinition eine Lösung für die Modellierung von Anwendungen über Objekte, die zugriffsfähig für bestimmte APIs und Bereiche sind.

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

subscription-key

Dies ist ein freigegebener Schlüssel, der bereitgestellt wird, wenn Sie Erstellen eines Azure Maps-Kontos im Azure-Portal oder mithilfe von PowerShell, CLI, Azure SDKs oder REST-API.

Mit diesem Schlüssel kann jede Anwendung auf alle REST-API zugreifen. Mit anderen Worten, dieser Schlüssel kann als Hauptschlüssel in dem Konto verwendet werden, in dem sie ausgestellt werden.

Für öffentlich zugängliche Anwendungen empfiehlt es sich, die vertraulichen Clientanwendungen Ansatz für den Zugriff auf Azure Maps-REST-APIs zu verwenden, damit Ihr Schlüssel sicher gespeichert werden kann.

Typ: apiKey
In: header

SAS Token

Dies ist ein Freigegebenes Zugriffssignaturtoken wird aus dem Listen-SAS-Vorgang auf der Azure Maps-Ressource über die Azure-Verwaltungsebene über das Azure-Portal, PowerShell, CLI, Azure SDKs oder REST-APIs erstellt.

Mit diesem Token ist jede Anwendung für den Zugriff mit rollenbasierten Azure-Zugriffssteuerungen und feinkörniger Kontrolle auf den Ablauf, die Rate und die Region(en) der Verwendung für das jeweilige Token autorisiert. Mit anderen Worten, das SAS-Token kann verwendet werden, um Anwendungen das Steuern des Zugriffs auf eine sicherere Weise zu ermöglichen als der freigegebene Schlüssel.

Für öffentlich zugängliche Anwendungen empfiehlt es sich, eine bestimmte Liste der zulässigen Ursprünge auf der Zuordnungskontoressource zu konfigurieren,, um das Rendern von Missbrauch zu begrenzen und das SAS-Token regelmäßig zu erneuern.

Typ: apiKey
In: header

Beispiele

Search detail address 15127 NE 24th Street, Redmond, WA

GET https://atlas.microsoft.com/geocode?api-version=2026-01-01&addressLine=15127 NE 24th Street&adminDistrict=WA&locality=Redmond

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "shortName": "WA"
            },
            {
              "shortName": "King County"
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "locality": "Redmond",
          "postalCode": "98052",
          "addressLine": "15127 NE 24th St"
        },
        "type": "Address",
        "confidence": "High",
        "matchCodes": [
          "Good"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.138681,
                47.630358
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          },
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.1386787,
                47.6302179
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Route"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.138681,
          47.630358
        ]
      },
      "bbox": [
        -122.14632282407,
        47.626495282429325,
        -122.13103917593001,
        47.63422071757068
      ]
    }
  ]
}

Search detail address 15127 NE 24th Street, Redmond, WA by addressLine

GET https://atlas.microsoft.com/geocode?api-version=2026-01-01&addressLine=15127 NE 24th Street Redmond WA&countryRegion=US

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "shortName": "WA"
            },
            {
              "shortName": "King County"
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "locality": "Redmond",
          "postalCode": "98052",
          "addressLine": "15127 NE 24th St"
        },
        "type": "Address",
        "confidence": "Medium",
        "matchCodes": [
          "Good"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.138681,
                47.630358
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          },
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.1386787,
                47.6302179
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Route"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.138681,
          47.630358
        ]
      },
      "bbox": [
        -122.14632282407,
        47.626495282429325,
        -122.13103917593001,
        47.63422071757068
      ]
    }
  ]
}

Search detail address 15127 NE 24th Street, Redmond, WA by query

GET https://atlas.microsoft.com/geocode?api-version=2026-01-01&query=15127 NE 24th Street Redmond WA

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "shortName": "WA"
            },
            {
              "shortName": "King County"
            }
          ],
          "formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
          "streetName": "NE 24th St",
          "streetNumber": "15127",
          "locality": "Redmond",
          "postalCode": "98052",
          "addressLine": "15127 NE 24th St"
        },
        "type": "Address",
        "confidence": "High",
        "matchCodes": [
          "Good"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.138681,
                47.630358
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          },
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -122.1386787,
                47.6302179
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Route"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.138681,
          47.630358
        ]
      },
      "bbox": [
        -122.14632282407,
        47.626495282429325,
        -122.13103917593001,
        47.63422071757068
      ]
    }
  ]
}

Search landmark Empire State Building by query

GET https://atlas.microsoft.com/geocode?api-version=2026-01-01&query=empire state building

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "shortName": "NY"
            }
          ],
          "formattedAddress": "Empire State Building, NY",
          "locality": "New York"
        },
        "type": "PointOfInterest",
        "confidence": "High",
        "matchCodes": [
          "Ambiguous"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -73.98580932617188,
                40.748435974121094
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.98580932617188,
          40.748435974121094
        ]
      },
      "bbox": [
        -73.98590850830078,
        40.74833679199219,
        -73.98571014404297,
        40.74853515625
      ]
    },
    {
      "type": "Feature",
      "properties": {
        "address": {
          "countryRegion": {
            "name": "United States"
          },
          "adminDistricts": [
            {
              "shortName": "NY"
            },
            {
              "shortName": "New York County"
            }
          ],
          "formattedAddress": "Empire State Building, NY",
          "locality": "Manhattan"
        },
        "type": "LandmarkBuilding",
        "confidence": "High",
        "matchCodes": [
          "Ambiguous"
        ],
        "geocodePoints": [
          {
            "geometry": {
              "type": "Point",
              "coordinates": [
                -73.98500061035156,
                40.74815368652344
              ]
            },
            "calculationMethod": "Rooftop",
            "usageTypes": [
              "Display"
            ]
          }
        ]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.98500061035156,
          40.74815368652344
        ]
      },
      "bbox": [
        -73.98710632324219,
        40.747314453125,
        -73.98412322998047,
        40.74958038330078
      ]
    }
  ]
}

Definitionen

Address

Die Adresse eines geokodierten oder autokomplett-vorgeschlagenen Ortes, in strukturierte Felder umgewandelt. Dünnheit ist normal: Nur die Felder, die die aufgelöste Entität bereitstellt, sind gefüllt. Zum Beispiel erscheinen streetName und streetNumber nur für Straßenadressen und intersection nur für Straßenkreuzungsergebnisse.

AddressAdminDistrictsItem

Eine Verwaltungsunterteilung, die eine Adresse enthält. Zum Beispiel ein Bundesstaat, eine Provinz oder ein Landkreis. Zurückgegeben als ein Eintrag im Elternarray Address.adminDistricts , wobei Einträge von grob bis feinst geordnet sind.

AddressCountryRegion

Das Land oder die Region, die die Adresse enthält, identifiziert durch ihren Anzeigenamen und den Ländercode ISO 3166-1 Alpha-2. Beide Felder können in einer gegebenen Antwort ausgelassen werden.

Azure.Core.Foundations.Error

Das Fehlerobjekt.

Azure.Core.Foundations.ErrorResponse

Eine Antwort, die Fehlerdetails enthält.

Azure.Core.Foundations.InnerError

Ein Objekt, das spezifischere Informationen zum Fehler enthält. Laut Azure REST API-Richtlinien – https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

Die Methode, die zum Berechnen des Geocodepunkts verwendet wurde.

ConfidenceEnum

Das Konfidenzniveau, dass das geocodierte Standortergebnis eine Übereinstimmung ist. Verwenden Sie diesen Wert zusammen mit den Spielcodes, um umfassendere Informationen über das Spiel zu erhalten.

Die Sicherheit eines geokodierten Ortes basiert auf vielen Faktoren, darunter die relative Bedeutung des geokodierten Ortes und des Standorts des Nutzers, sofern angegeben.

FeatureCollectionEnum

Der GeoJSON Objekttyp, der als Wurzel erfolgreicher Antworten aus den Vorwärts-Geocoding-, Reverse-Geocoding- und Autocomplete-Operationen (einschließlich ihrer Batch-Varianten) verwendet wird. Der einzige Wert ist FeatureCollection, wie in RFC 7946 definiert. Get Polygon ist die eine Ausnahme: Seine Antwortwurzel ist eine GeoJSON Feature, siehe FeatureTypeEnum.

FeaturesItem

Ein einzelner Eintrag im features Array eines GeocodingResponse, der der GeoJSON Feature Objektform entspricht. Repräsentiert einen geokodierten Ort: strukturierte Daten auf properties, eine repräsentative Koordinate auf geometry, und eine optionale Begrenzungsbox auf bbox.

FeaturesItemProperties

Die Nutzlast properties eines Merkmals in einem GeocodingResponse. Enthält die Entitätstyp- und Match-Qualitätsindikatoren für den geokodierten Standort, seine geparsten Adresskomponenten sowie einen oder mehrere Geocode-Punkte, die den Standort auf bestimmte Koordinaten festlegen.

FeatureTypeEnum

Der GeoJSON Objekttyp für Feature Objekte. Markiert jeden Eintrag innerhalb des features Arrays einer Antwort FeatureCollection (Geocoding, Reverse Geocoding, Autocomplete) und erscheint an der Wurzel der Antwort Get Polygon . Der einzige Wert ist Feature, wie in RFC 7946 definiert.

GeocodePointsItem

Ein Geocode-Punkt für einen Ort: eine Koordinate plus Metadaten, die beschreiben, wie der Punkt berechnet wurde (calculationMethod) und wofür er am besten geeignet ist (usageTypes). Ein einzelnes Merkmal gibt in der Regel separate Display Punkte Route zurück, sodass Anrufer das auswählen können, das zur Aufgabe passt.

GeocodingResponse

Der erfolgreiche Antwortkörper wurde von Get Geocoding und Get Reverse Geocodingzurückgegeben, sowie die pro-Charge-Item-Erfolgsform, die im Inneren GeocodingBatchResponse.batchItemsgeführt wurde. Codiert als ein GeoJSON FeatureCollection Array, dessen features Array pro geokodiertem Standort eines Feature enthält.

GeoJsonObjectType

Gibt den GeoJSON Typ an. Muss einer der neun gültigen GeoJSON-Objekttypen sein : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature und FeatureCollection.

GeoJsonPoint

Ein gültiger GeoJSON Point Geometrietyp. Weitere Informationen finden Sie unter RFC 7946-.

Intersection

Kreuzungsdetails für eine Adresse, die als Straßenkreuzung definiert ist – die Ecke, an der sich zwei oder mehr benannte Straßen treffen. Nur dann gefüllt, wenn die aufgelöste Entität ein RoadIntersectionist; der Elternteil Address.intersection wird ansonsten weggelassen.

MatchCodesEnum

Ein Match-Code-Wert, der angibt, wie der Geocodierungsdienst ein bestimmtes Standortergebnis erzeugt hat. Das Feld matchCodes auf einem Merkmal ist ein Array dieser Werte; kombinieren Sie sie mit confidence und type um die Übereinstimmung zu bewerten.

UsageTypeEnum

Die beabsichtigte Verwendung für einen Geocode-Punkt. Ein vom Dienst zurückgegebener Geocode-Punkt trägt eine oder mehrere Nutzungstypen, die angeben, wie eine Client-Anwendung den Punkt konsumieren soll: zum Beispiel die Anzeige des Ortes auf einer Karte im Vergleich zur Weiterleitung eines Fahrzeugs dorthin.