Search - Get Reverse Geocoding Batch

Verwenden Sie diese Option, um einen Batch von Abfragen in einer einzigen Anforderung an die Reverse Geocoding-API zu senden.
Die Get Reverse Geocoding Batch-API ist eine HTTP-POST-Anforderung, die Batches von bis zu 100 Abfragen an Reverse Geocoding API mithilfe einer einzigen Anforderung sendet.

Synchrone Batchanforderung übermitteln

Die synchrone API wird für einfache Batchanforderungen empfohlen. Wenn der Dienst eine Anforderung empfängt, antwortet er, sobald die Batchelemente berechnet werden, und es besteht keine Möglichkeit, die Ergebnisse später abzurufen. Die synchrone API gibt einen Timeoutfehler (eine 408-Antwort) zurück, wenn die Anforderung länger als 60 Sekunden dauert. Die Anzahl der Batchelemente ist auf 100 für diese API beschränkt.

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version={api-version}

POST-Text für Batchanforderung

Um die umgekehrte Geocodierung Abfragen zu senden, verwenden Sie eine POST Anforderung, bei der der Anforderungstext das batchItems Array im json Format enthält, und der Content-Type Header wird auf application/jsonfestgelegt. Hier ist ein Beispielanforderungstext mit 2 umgekehrten Geocodierung Abfragen:

{
  "batchItems": [
    {
      "coordinates": [-122.128275, 47.639429],
      "resultTypes": ["Address", "PopulatedPlace"]
    },
    {
      "coordinates": [-122.341979399674, 47.6095253501216]
    }
  ]
}

Ein umgekehrte Geocodierung batchItem-Objekt kann jedes der unterstützten umgekehrten GeocodierungsparameterURI-Parameterakzeptieren.

Der Batch sollte mindestens 1 Abfrage enthalten.

Batchantwortmodell

Die Batchantwort enthält eine summary Komponente, die die totalRequests angibt, die Teil der ursprünglichen Batchanforderung waren, und successfulRequests d. h. Abfragen, die erfolgreich ausgeführt wurden. Die Batchantwort enthält auch ein batchItems Array, das eine Antwort für jede und jede Abfrage in der Batchanforderung enthält. Die batchItems enthält die Ergebnisse in der genauen Reihenfolge, in der die ursprünglichen Abfragen in der Batchanforderung gesendet wurden. Jedes Element weist einen der folgenden Typen auf:

• GeocodingResponse – Wenn die Abfrage erfolgreich abgeschlossen wurde.

• Error – Wenn die Abfrage fehlgeschlagen ist. Die Antwort enthält in diesem Fall eine code und eine message.

POST {endpoint}/reverseGeocode:batch?api-version=2026-01-01

URI-Parameter

Anforderungsheader

Anforderungstext

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

A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2026-01-01

{
  "batchItems": [
    {
      "coordinates": [
        -122.138681,
        47.630358
      ],
      "resultTypes": [
        "Address",
        "PopulatedPlace"
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "coordinates": [
        47.630358,
        -122.138681
      ],
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "type": "Address",
            "confidence": "Medium",
            "matchCodes": [
              "Good"
            ],
            "address": {
              "locality": "Redmond",
              "adminDistricts": [
                {
                  "name": "Washington",
                  "shortName": "WA"
                },
                {
                  "name": "King County",
                  "shortName": "King Co."
                }
              ],
              "countryRegion": {
                "ISO": "US",
                "name": "United States"
              },
              "postalCode": "98052",
              "formattedAddress": "2267 152nd Ave NE, Redmond, Washington 98052, United States",
              "streetName": "152nd Ave NE",
              "streetNumber": "2267",
              "addressLine": "2267 152nd Ave NE"
            },
            "geocodePoints": [
              {
                "geometry": {
                  "type": "Point",
                  "coordinates": [
                    -122.128275,
                    47.639429
                  ]
                },
                "calculationMethod": "Rooftop",
                "usageTypes": [
                  "Display",
                  "Route"
                ]
              },
              {
                "geometry": {
                  "type": "Point",
                  "coordinates": [
                    -122.127028,
                    47.638545
                  ]
                },
                "calculationMethod": "Rooftop",
                "usageTypes": [
                  "Route"
                ]
              }
            ]
          },
          "geometry": {
            "type": "Point",
            "coordinates": [
              -122.128275,
              47.639429
            ]
          },
          "bbox": [
            -122.1359181505759,
            47.63556628242932,
            -122.1206318494241,
            47.643291717570676
          ]
        }
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "error": {
        "code": "Bad Request",
        "message": "The provided coordinates (-122.138681,47.630358) in coordinates field are invalid or out of range"
      },
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

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.

ErrorAdditionalInfo

Der Ressourcenverwaltungsfehler zusätzliche Informationen.

ErrorDetail

Das Fehlerdetails.

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.

GeocodingBatchResponse

Der erfolgreiche Antwortkörper wurde durch zurückgegeben Get Geocoding Batch. Enthält eine summary Anzahl der erfolgreichen Anzahl der eingereichten Abfragen plus ein Array, batchItems das pro Abfrage in der Anfrage einen Antworteintrag enthält, in derselben Reihenfolge wie das Anforderungsarray batchItems .

GeocodingBatchResponseItem

Ein einzelner Eintrag in GeocodingBatchResponse.batchItems, der das Ergebnis einer der Abfragen aus dem entsprechenden GeocodingBatchRequestBody.batchItems Eintrag enthält. Erfolgreiche Abfragen werden hier geokodiert features in der gleichen Form wie GeocodingResponseangezeigt. Fehlgeschlagene Abfragen zeigen stattdessen diagnostische Informationen über error . Genau eines von features oder error wird pro Eintrag ausgefüllt.

GeocodingBatchResponseSummary

Enthält aggregierte Zählungen für eine Get Geocoding Batch Antwort: die Größe des eingereichten Batches und wie viele seiner Anfragen erfolgreich verarbeitet wurden. Verwendet als die Art von GeocodingBatchResponse.summary.

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.

ResultTypeEnum

Ein Entitätstyp, der durch die Operation zurückgegeben wird Get Reverse Geocoding Batch . Sie werden als ein oder mehrere Werte im Feld pro Batch resultTypes angegeben, um die Antwort für diesen Artikel auf bestimmte Arten von Standorten zu beschränken; wenn das Feld weggelassen wird, sind alle Entitätstypen berechtigt. Wenn Entitäten mehrerer Typen einer Koordinate entsprechen, wird nur die spezifischste zurückgegeben. Von am spezifischsten bis am wenigsten spezifisch aufgelistet: Address, , , PopulatedPlace, AdminDivision1Postcode1, AdminDivision2, , CountryRegionNeighborhood.

ReverseGeocodingBatchRequestBody

Die Anfrage für die Get Reverse Geocoding Batch Operation. Trägt eine oder mehrere einzelne Reverse-Geocoding-Abfragen – zwischen 1 und 100 – die der Dienst als einen einzigen Anruf verarbeitet und als paralleles batchItems Array auf GeocodingBatchResponsezurückgibt.

ReverseGeocodingBatchRequestItem

Eine Reverse-Geocoding-Abfrage innerhalb eines Arrays ReverseGeocodingBatchRequestBody.batchItems . Jedes Element ist eine unabhängige Reverse-Geocoding-Anfrage, die einem einzelnen Aufruf von Get Reverse Geocodingentspricht, ausgedrückt als Felder statt als URL-Abfrageparameter. Geben Sie den Standort an, der mit rückwärts geokodiert werden soll coordinates; optional werden die Entitätstypen über resultTypes und die geopolitische Ansicht über vieweingegrenzt.

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.