Search - Get Reverse Geocoding Batch

Umożliwia wysłanie partii zapytań do interfejsu API geokodowania wstecznego w jednym żądaniu.
Interfejs API Get Reverse Geocoding Batch to żądanie POST HTTP, które wysyła partie do 100 zapytań w celu odwrotnego geokodowania interfejsu API przy użyciu pojedynczego żądania.

Przesyłanie synchronicznego żądania usługi Batch

Interfejs API synchroniczny jest zalecany w przypadku lekkich żądań wsadowych. Gdy usługa odbierze żądanie, odpowie natychmiast po obliczeniu elementów wsadowych i nie będzie możliwe późniejsze pobranie wyników. Interfejs API synchroniczny zwróci błąd limitu czasu (odpowiedź 408), jeśli żądanie trwa dłużej niż 60 sekund. Liczba elementów wsadowych jest ograniczona do 100 dla tego interfejsu API.

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

Treść POST dla żądania wsadowego

Aby wysłać zapytania odwrotnego geokodowania, użyjesz żądania , w którym treść żądania będzie zawierać tablicę w formacie , a nagłówek zostanie ustawiony na wartość . Oto przykładowa treść żądania zawierająca 2 odwrotne geokodowanie zapytań:

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

Obiekt odwrotnego geokodowania batchItem może zaakceptować dowolny z obsługiwanych odwrotnego geokodowaniaparametrów identyfikatora URI.

Partia powinna zawierać co najmniej 1 kwerendy.

Model odpowiedzi wsadowej

Odpowiedź wsadowa zawiera składnik summary wskazujący totalRequests, które były częścią oryginalnego żądania wsadowego i successfulRequests tj. zapytania, które zostały wykonane pomyślnie. Odpowiedź wsadowa zawiera również tablicę batchItems zawierającą odpowiedź dla każdego zapytania w żądaniu wsadowym. batchItems będzie zawierać wyniki w dokładnie takiej samej kolejności, w jaki oryginalne zapytania zostały wysłane w żądaniu wsadowym. Każdy element jest jednym z następujących typów:

• GeocodingResponse — jeśli zapytanie zostało ukończone pomyślnie.

• Error — jeśli zapytanie nie powiodło się. Odpowiedź będzie zawierać code i message w tym przypadku.

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

Parametry identyfikatora URI

Nagłówek żądania

Treść żądania

Odpowiedzi

Zabezpieczenia

AadToken

Są to przepływy Microsoft Entra OAuth 2.0. W połączeniu z Azure zarządzaniem dostępem opartym na rolach może być używany do kontroli dostępu do Azure Maps API REST. Kontrola dostępu oparta na rolach Azure służy do wyznaczania dostępu do jednego lub więcej kont zasobów lub podzasobów Azure Maps. Każdy użytkownik, grupa lub jednostka usługi mogą mieć dostęp za pośrednictwem wbudowanej roli lub roli niestandardowej składającej się z co najmniej jednego uprawnienia do interfejsów API REST usługi Azure Maps.

Aby zaimplementować scenariusze, zalecamy wyświetlenie koncepcji uwierzytelniania . Podsumowując, ta definicja zabezpieczeń zawiera rozwiązanie do modelowania aplikacji za pośrednictwem obiektów, które mogą kontrolować dostęp do określonych interfejsów API i zakresów.

Typ: oauth2
Flow: implicit
Adres URL autoryzacji: https://login.microsoftonline.com/common/oauth2/authorize

Zakresy

subscription-key

Jest to klucz wspólny aprowizowany podczas tworzenie konta usługi Azure Maps w witrynie Azure Portal lub przy użyciu programu PowerShell, interfejsu wiersza polecenia, zestawów SDK platformy Azure lub interfejsu API REST.

Za pomocą tego klucza każda aplikacja może uzyskiwać dostęp do całego interfejsu API REST. Innymi słowy, ten klucz może służyć jako klucz główny na koncie, w którym są wystawiane.

W przypadku publicznie uwidocznionych aplikacji zalecamy użycie poufnych aplikacji klienckich podejście do uzyskiwania dostępu do interfejsów API REST usługi Azure Maps, aby klucz mógł być bezpiecznie przechowywany.

Typ: apiKey
W: header

SAS Token

Jest to token sygnatury dostępu współdzielonego tworzony na podstawie operacji List SAS na zasobie usługi Azure Maps za pośrednictwem płaszczyzny zarządzania platformy Azure za pośrednictwem witryny Azure Portal, programu PowerShell, interfejsu wiersza polecenia, zestawów AZURE SDK lub interfejsów API REST.

Dzięki temu tokenowi każda aplikacja jest autoryzowana do uzyskiwania dostępu za pomocą kontroli dostępu opartej na rolach platformy Azure i szczegółowej kontroli wygaśnięcia, szybkości i regionów użycia dla określonego tokenu. Innymi słowy, token SAS może służyć do umożliwienia aplikacjom kontrolowania dostępu w sposób bardziej zabezpieczony niż klucz wspólny.

W przypadku publicznie uwidocznionych aplikacji zalecamy skonfigurowanie określonej listy dozwolonych źródeł w zasobie Mapowanie konta w celu ograniczenia nadużyć renderowania i regularnego odnawiania tokenu SAS.

Typ: apiKey
W: header

Przykłady

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"
    }
  ]
}

Definicje

Address

Adres geokodowanej lub automatycznie uzupełniającej lokalizacji, podzielonej na pola strukturalne. Rzadkość jest normalna: wypełniane są tylko pola dostarczane przez rozdzieloną jednostkę. Na przykład streetName i pojawiają się streetNumber tylko dla adresów na poziomie ulicy i intersection pojawiają się tylko dla wyników skrzyżowań drogowych.

AddressAdminDistrictsItem

Podział administracyjny, który zawiera adres. Na przykład stan, prowincja lub hrabstwo. Zwracany jako jeden element w tablicy nadrzędnej Address.adminDistricts , gdzie wpisy są uporządkowane od najgrubszego do najcieńszego.

AddressCountryRegion

Kraj lub region, który zawiera adres, oznaczony nazwą wyświetlaną oraz kodem kraju ISO 3166-1 Alpha-2. W odpowiedzi można pominąć każde z tych pól.

Azure.Core.Foundations.Error

Obiekt błędu.

Azure.Core.Foundations.ErrorResponse

Odpowiedź zawierająca szczegóły błędu.

Azure.Core.Foundations.InnerError

Obiekt zawierający bardziej szczegółowe informacje o błędzie. Zgodnie z Azure wytycznymi API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

Metoda, która została użyta do obliczenia punktu kodu geograficznego.

ConfidenceEnum

Poziom pewności, że wynik geokodowanej lokalizacji jest zgodny. Użyj tej wartości wraz z kodami dopasowania, aby uzyskać bardziej szczegółowe informacje o dopasowaniu.

Pewność lokalizacji geokodowanej zależy od wielu czynników, w tym względnego znaczenia lokalizacji oraz lokalizacji użytkownika, jeśli jest to wskazane.

ErrorAdditionalInfo

Dodatkowe informacje o błędzie zarządzania zasobami.

ErrorDetail

Szczegóły błędu.

FeatureCollectionEnum

Typ GeoJSON obiektu używany u podstawy udanych odpowiedzi z operacji geokodowania do przodu, geokodowania odwrotnego oraz autouzupełniania (w tym ich wariantów wsadowych). Jedyną wartością FeatureCollectionjest , zgodnie z definicją RFC 7946. Get Polygon jest jedynym wyjątkiem: jego pierwiastek odpowiedzi to GeoJSON Feature, zobacz FeatureTypeEnum.

FeaturesItem

Pojedynczy wpis w tablicy features , GeocodingResponsezgodny z kształtem obiektu GeoJSON Feature . Reprezentuje jedną lokalizację geokodowaną: dane strukturalne na , propertiesreprezentatywną współrzędną na geometry, oraz opcjonalne ramki ograniczające na bbox.

FeaturesItemProperties

Ładunek properties funkcji w .GeocodingResponse Zawiera wskaźniki typu encji i jakości dopasowania dla geokodowanej lokalizacji, jej przeanalizowanych komponentów adresowych oraz jednego lub więcej punktów geokodowych przypisujących lokalizację do określonych współrzędnych.

FeatureTypeEnum

Typ obiektu GeoJSON dla Feature obiektów. Oznacza każdy wpis wewnątrz tablicy featuresFeatureCollection odpowiedzi (geokodowanie, geokodowanie odwrotne, autouzupełnianie) i pojawia się u podstawy Get Polygon odpowiedzi. Jedyną wartością Featurejest , zgodnie z definicją RFC 7946.

GeocodePointsItem

Jeden punkt geokodowy dla lokalizacji: współrzędna wraz z metadanymi opisującymi, jak dany punkt został obliczony (calculationMethod) i do czego jest najlepiej przystosowany (usageTypes). Pojedyncza cecha zazwyczaj zwraca oddzielne Display i Route punkty, dzięki czemu dzwoniący mogą wybrać tę, która odpowiada zadaniu.

GeocodingBatchResponse

Udana jednostka odpowiedzi zwrócona przez Get Geocoding Batch. Zawiera liczbę summary zakończonych zapytań plus tablicę batchItems zawierającą jeden wpis odpowiedzi na każde zapytanie w żądaniu, w tej samej kolejności co tablica żądań batchItems .

GeocodingBatchResponseItem

Pojedynczy wpis wewnątrz GeocodingBatchResponse.batchItems, zawierający wynik jednego z zapytań z odpowiadającego GeocodingBatchRequestBody.batchItems wpisu. Udane zapytania pojawiają się tutaj jako geokodowane features w tym samym kształcie co GeocodingResponse; nieudane zapytania wyświetlają informacje diagnostyczne przez zamiast error tego. Dokładnie jedno z features lub error jest wypełnione na każde wpisanie.

GeocodingBatchResponseSummary

Carry łączy łączną liczbę odpowiedzi Get Geocoding Batch : wielkość wysłanej partii oraz liczbę jej zapytań zostało pomyślnie przetworzonych. Używany jako typ .GeocodingBatchResponse.summary

GeoJsonObjectType

Określa typ GeoJSON. Musi być jednym z dziewięciu prawidłowych typów obiektów GeoJSON — Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature i FeatureCollection.

GeoJsonPoint

Prawidłowy typ geometrii GeoJSON Point. Aby uzyskać szczegółowe informacje, zobacz RFC 7946.

Intersection

Szczegóły skrzyżowania dla adresu rozstrzygniętego jako skrzyżowanie drogowe — narożnik, na którym spotykają się dwie lub więcej nazwanych ulic. Wypełnia się tylko wtedy, gdy rozwiązana jednostka jest ; RoadIntersectionrodzic Address.intersection jest pomijany.

MatchCodesEnum

Wartość kodu dopasowania wskazująca, jak usługa geokodowania wygenerowała konkretny wynik lokalizacji. Pole matchCodes na cechie to tablica tych wartości; połącz je z confidence i type aby ocenić jakość dopasowania.

ResultTypeEnum

Typ jednostki zwracany przez operację Get Reverse Geocoding Batch . Podawane jako jedna lub więcej wartości w polu na partię-element resultTypes , aby ograniczyć odpowiedź dla tego elementu do określonych typów lokalizacji; gdy pole zostanie pominięte, wszystkie typy encji są kwalifikowane. Gdy byty więcej niż jednego typu odpowiadają współrzędnej, zwracana jest tylko najbardziej szczegółowa jednostka. Od najbardziej szczegółowego do najmniej szczegółowego: , , , , , AdminDivision1, , AdminDivision2. CountryRegionPostcode1PopulatedPlaceNeighborhoodAddress

ReverseGeocodingBatchRequestBody

Ciało z żądaniami do operacji Get Reverse Geocoding Batch . Przenosi jedno lub więcej indywidualnych zapytań odwrotnego geokodowania — od 1 do 100, włącznie — które usługa przetwarza jako jedno wywołanie i zwraca jako tablicę równoległą batchItems na .GeocodingBatchResponse

ReverseGeocodingBatchRequestItem

Jedno zapytanie odwrotnego geokodowania wewnątrz tablicy ReverseGeocodingBatchRequestBody.batchItems . Każdy element jest niezależnym żądaniem odwrotnego geokodowania, równoważnym pojedynczemu wywołaniu , Get Reverse Geocodingwyrażonym jako pola, a nie jako parametry zapytania URL. Określ lokalizację do odwrócenia geokodu za pomocą coordinates; opcjonalnie zawęż typy jednostek przez , resultTypes a widok geopolityczny przez view.

UsageTypeEnum

Przeznaczone zastosowanie punktu geokodowego. Punkt geokodowy zwracany przez usługę niesie jeden lub więcej typów użycia, które wskazują, jak aplikacja kliencka powinna wykorzystać ten punkt: na przykład wyświetlanie lokalizacji na mapie zamiast kierowania pojazdu do niej.