Search - Get Reverse Geocoding Batch

Permet d’envoyer un lot de requêtes à l’API de géocodage inverse en une seule requête.
L’API Get Reverse Geocoding Batch est une requête HTTP POST qui envoie des lots allant jusqu’à 100 requêtes pour géocodage inverse API à l’aide d’une seule requête.

Envoyer une demande de traitement par lots synchrone

L’API synchrone est recommandée pour les requêtes par lots légères. Lorsque le service reçoit une demande, il répond dès que les éléments de lot sont calculés et il n’y aura aucune possibilité de récupérer les résultats ultérieurement. L’API synchrone retourne une erreur de délai d’expiration (réponse 408) si la requête prend plus de 60 secondes. Le nombre d’éléments de lot est limité à 100 pour cette API.

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

Corps POST pour la requête Batch

Pour envoyer le géocodage inverse requêtes, vous utiliserez une requête POST où le corps de la requête contiendra le tableau batchItems au format json et l’en-tête Content-Type sera défini sur application/json. Voici un exemple de corps de requête contenant 2 géocodage inverse requêtes :

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

Un géocodage inverse objet batchItem peut accepter l’un des paramètres de géocodage inverse pris en charged’URI.

Le lot doit contenir au moins 1 requête.

Modèle de réponse par lot

La réponse par lot contient un composant summary qui indique les totalRequests qui faisaient partie de la demande de lot d’origine et successfulRequests c’est-à-dire les requêtes qui ont été exécutées avec succès. La réponse par lot inclut également un tableau batchItems qui contient une réponse pour chaque requête dans la requête de lot. Les batchItems contiennent les résultats dans le même ordre que les requêtes d’origine ont été envoyées dans la requête de lot. Chaque élément est de l’un des types suivants :

• GeocodingResponse : si la requête s’est terminée correctement.

• Error : si la requête a échoué. La réponse contient une code et une message dans ce cas.

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

Paramètres URI

En-tête de la demande

Corps de la demande

Réponses

Sécurité

AadToken

Ce sont les flux Microsoft Entra OAuth 2.0. Lorsqu’il est associé au contrôle d’accès basé sur Azure par rôle, il peut être utilisé pour contrôler l’accès à Azure Maps API REST. Les contrôles d’accès basés sur les rôles Azure sont utilisés pour désigner l’accès à un ou plusieurs comptes ou sous-ressources de ressources Azure Maps. Tout utilisateur, groupe ou principal de service peut avoir accès via un rôle intégré ou un rôle personnalisé composé d’une ou plusieurs autorisations pour les API REST Azure Maps.

Pour implémenter des scénarios, nous vous recommandons d’afficher concepts d’authentification. En résumé, cette définition de sécurité fournit une solution pour la modélisation des applications via des objets capables de contrôler l’accès sur des API et des étendues spécifiques.

Type: oauth2
Flux: implicit
URL d’autorisation: https://login.microsoftonline.com/common/oauth2/authorize

Étendues

subscription-key

Il s’agit d’une clé partagée provisionnée lorsque vous créer un compte Azure Maps dans le portail Azure ou à l’aide de PowerShell, CLI, sdk Azure ou API REST.

Avec cette clé, toute application peut accéder à toutes les API REST. En d’autres termes, cette clé peut être utilisée comme clé principale dans le compte dans lequel elles sont émises.

Pour les applications exposées publiquement, nous vous recommandons d’utiliser les applications clientes confidentielles approche permettant d’accéder aux API REST Azure Maps afin que votre clé puisse être stockée en toute sécurité.

Type: apiKey
Dans: header

SAS Token

Il s’agit d’un jeton de signature d’accès partagé créé à partir de l’opération List SAS sur la ressource Azure Maps via le plan de gestion Azure via le portail Azure, PowerShell, CLI, azure SDK ou LES API REST.

Avec ce jeton, toute application est autorisée à accéder avec des contrôles d’accès en fonction du rôle Azure et un contrôle précis à l’expiration, au taux et aux régions d’utilisation pour le jeton particulier. En d’autres termes, le jeton SAP peut être utilisé pour permettre aux applications de contrôler l’accès de manière plus sécurisée que la clé partagée.

Pour les applications exposées publiquement, nous vous recommandons de configurer une liste spécifique d’origines autorisées sur la ressource de compte mapper pour limiter l’abus de rendu et renouveler régulièrement le jeton SAP.

Type: apiKey
Dans: header

Exemples

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

Définitions

Address

L’adresse d’un emplacement suggéré par géocodage ou autocomplétion, analysé en champs structurés. La rareté est normale : seuls les champs fournis par l’entité résolue sont peuplés. Par exemple, streetName et streetNumber apparaissent uniquement pour les adresses au niveau de la rue, et intersection apparaissent uniquement pour les résultats d’intersections routières.

AddressAdminDistrictsItem

Un lotissement administratif contenant une adresse. Par exemple, un État, une province ou un comté. Retourné comme une seule entrée dans le tableau parent Address.adminDistricts , où les entrées sont ordonnées du plus grossier au plus fin.

AddressCountryRegion

Le pays ou la région contenant l’adresse, identifié par son nom d’affichage et le code pays ISO 3166-1 Alpha-2. L’un ou l’autre champ peut être omis dans une réponse donnée.

Azure.Core.Foundations.Error

Objet d’erreur.

Azure.Core.Foundations.ErrorResponse

Réponse contenant les détails de l’erreur.

Azure.Core.Foundations.InnerError

Objet contenant des informations plus spécifiques sur l’erreur. Selon Azure directives de l’API REST - https://aka.ms/AzureRestApiGuidelines#handling-errors.

CalculationMethodEnum

Méthode utilisée pour calculer le point de géocodeur.

ConfidenceEnum

Le niveau de confiance que le résultat de l’emplacement géocodé est une correspondance. Utilisez cette valeur avec les codes de correspondance pour obtenir des informations plus complètes sur la correspondance.

La confiance d’un emplacement géocodé dépend de nombreux facteurs, notamment l’importance relative de l’emplacement géocodé et la localisation de l’utilisateur, si spécifiée.

ErrorAdditionalInfo

Informations supplémentaires sur l’erreur de gestion des ressources.

ErrorDetail

Détail de l’erreur.

FeatureCollectionEnum

Le type d’objet GeoJSON utilisé à la base des réponses réussies issues des opérations de géocodage direct, de géocodage inverse et d’autocomplétion (y compris leurs variantes par lot). La seule valeur est FeatureCollection, telle que définie dans la RFC 7946. Get Polygon est la seule exception : sa racine de réponse est un GeoJSON Feature, voir FeatureTypeEnum.

FeaturesItem

Une seule entrée dans le features tableau de un GeocodingResponse, conforme à la forme de l’objet GeoJSON Feature . Représente un emplacement géocodé : données structurées sur properties, une coordonnée représentative sur geometry, et une boîte englobante optionnelle sur bbox.

FeaturesItemProperties

La properties charge utile d’une caractéristique dans un GeocodingResponsefichier . Contient les indicateurs de type d’entité et de qualité de correspondance pour la localisation géocodée, ses composantes d’adresse analysées, ainsi qu’un ou plusieurs points géocodés qui associent la localisation à des coordonnées spécifiques.

FeatureTypeEnum

Le type d’objet GeoJSON pour Feature les objets. Étiquete chaque entrée dans le features tableau d’une FeatureCollection réponse (géocodage, géocodage inverse, autocomplétion) et apparaît à la racine de la Get Polygon réponse. La seule valeur est Feature, telle que définie dans la RFC 7946.

GeocodePointsItem

Un point de géocodage pour un emplacement : une coordonnée plus des métadonnées décrivant comment le point a été calculé (calculationMethod) et à quoi il convient le mieux (usageTypes). Une seule fonctionnalité retourne généralement un élément séparé Display et Route pointe pour que les appelants puissent choisir celle qui convient à la tâche.

GeocodingBatchResponse

Le corps de réponse réussi a répondu par Get Geocoding Batch. Contient le summary nombre de requêtes soumises réussies ainsi qu’un batchItems tableau contenant une entrée de réponse par requête dans la requête, dans le même ordre que le tableau de requêtes batchItems .

GeocodingBatchResponseItem

Une seule entrée à l’intérieur GeocodingBatchResponse.batchItemsde , portant le résultat d’une des requêtes de l’entrée correspondante GeocodingBatchRequestBody.batchItems . Les requêtes réussies apparaissent leur géocodée features ici sous la même forme que GeocodingResponse; requêtes échouées présentent des informations de diagnostic via error instead. Exactement un de features ou error est rempli par entrée.

GeocodingBatchResponseSummary

Contient les comptes agrégés pour une Get Geocoding Batch réponse : la taille du lot soumis et le nombre de requêtes traitées avec succès. Utilisé comme type de GeocodingBatchResponse.summary.

GeoJsonObjectType

Spécifie le type GeoJSON. Doit être l’un des neuf types d’objets GeoJSON valides : Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature et FeatureCollection.

GeoJsonPoint

Type de géométrie GeoJSON Point valide. Pour plus d’informations, reportez-vous à RFC 7946.

Intersection

Les détails de l’intersection d’une adresse sont définis comme un intersection routière — le coin où deux rues nommées ou plus se rejoignent. Rempli uniquement lorsque l’entité résolue est un RoadIntersection; le parent Address.intersection est autrement omis.

MatchCodesEnum

Une valeur de code correspondant indiquant comment le service de géocodage a produit un résultat de localisation donné. Le matchCodes champ sur une caractéristique est un tableau de ces valeurs ; combinez-les avec confidence et type pour évaluer la qualité de correspondance.

ResultTypeEnum

Un type d’entité retourné par l’opération Get Reverse Geocoding Batch . Fourni sous forme d’une ou plusieurs valeurs dans le champ par lot resultTypes pour restreindre la réponse de cet élément à des types spécifiques d’emplacements ; lorsque le champ est omis, tous les types d’entités sont éligibles. Lorsque des entités de plus d’un type correspondent à une coordonnée, seule la plus spécifique est retournée. Listé du plus spécifique au moins spécifique : Address, Neighborhood, PopulatedPlacePostcode1, AdminDivision1, , AdminDivision2, , . CountryRegion

ReverseGeocodingBatchRequestBody

L’organisme demandeur pour l’opération Get Reverse Geocoding Batch . Transporte une ou plusieurs requêtes individuelles de géocodage inversé — entre 1 et 100, inclus — que le service traite en un seul appel et renvoie sous forme de tableau parallèle batchItems sur GeocodingBatchResponse.

ReverseGeocodingBatchRequestItem

Une requête de géocodage inversé à l’intérieur d’un ReverseGeocodingBatchRequestBody.batchItems tableau. Chaque élément est une demande indépendante de géocodage inversé équivalente à un seul appel à Get Reverse Geocoding, exprimée comme des champs plutôt que comme des paramètres de requête URL. Spécifier l’emplacement à rétrocoder via coordinates; éventuellement restreindre les types d’entités via resultTypes et la vue géopolitique via view.

UsageTypeEnum

L’utilisation prévue d’un point de géocodage. Un point de géocodage retourné par le service porte un ou plusieurs types d’utilisation qui indiquent comment une application cliente doit consommer le point : par exemple, afficher l’emplacement sur une carte versus y acheminer un véhicule.