Search - Post Search Address Reverse Batch

Permet d’envoyer un lot de requêtes à l’API d’adresse inverse Recherche dans une requête asynchrone unique.

L’API Post Search Address Reverse Batch est une requête HTTP POST qui envoie des lots de requêtes à Recherche’API Address Reverse dans un seul appel d’API asynchrone. Vous pouvez appeler Post Search Address Reverse Batch l’API pour qu’elle s’exécute de manière asynchrone (asynchrone) ou synchrone (synchronisation). L’API asynchrone permet à l’appelant de traiter par lot jusqu’à 10 000 requêtes et de synchroniser l’API jusqu’à 100 requêtes.

Envoyer une demande de lot synchrone

L’API synchrone est recommandée pour les demandes de 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’est plus possible 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 demande prend plus de 60 secondes. Le nombre d’éléments de lot est limité à 100 pour cette API.

POST https://atlas.microsoft.com/search/address/reverse/batch/sync/json?api-version=1.0&subscription-key={subscription-key}

Envoyer une demande de lot asynchrone

L’API asynchrone est appropriée pour traiter de gros volumes de demandes de recherche relativement complexes

• Il permet la récupération des résultats dans un appel distinct (plusieurs téléchargements sont possibles).
• L’API asynchrone est optimisée pour la fiabilité et n’est pas censée avoir un délai d’expiration.
• Le nombre d’éléments de lot est limité à 10 000 pour cette API.

Lorsque vous effectuez une demande à l’aide d’une requête asynchrone, par défaut, le service retourne un code de réponse 202 le long d’une URL de redirection dans le champ Emplacement de l’en-tête de réponse. Cette URL doit être vérifiée régulièrement jusqu’à ce que les données de réponse ou les informations d’erreur soient disponibles. Les réponses asynchrones sont stockées pendant 14 jours. L’URL de redirection retourne une réponse 404 si elle est utilisée après la période d’expiration.

Notez que la requête par lot asynchrone est une opération de longue durée. Voici une séquence classique d’opérations :

1. Le client envoie une Recherche demande de traitement par lots POST inversée à Azure Maps.

POST https://atlas.microsoft.com/search/address/reverse/batch/json?api-version=1.0&subscription-key={subscription-key}

2. Le serveur répond avec l’une des opérations suivantes :

   HTTP 202 Accepted : la requête Batch a été acceptée.

   HTTP Error : une erreur s’est produite lors du traitement de votre requête Batch. Il peut s’agir d’un 400 Bad Request code status ou de tout autre Error code.

3. Si la demande de lot a été acceptée avec succès, l’en-tête Location de la réponse contient l’URL permettant de télécharger les résultats de la demande de lot. Cet URI status se présente comme suit :

    GET https://atlas.microsoft.com/search/address/reverse/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

4. Le client émet une GET demande sur l’URL de téléchargement obtenue à l’étape 3 pour télécharger les résultats du lot.

Corps POST pour la demande de lot

Pour envoyer les requêtes inversées d’adresse de recherche , vous utiliserez une POST requête dans laquelle le corps de la demande contiendra le batchItems tableau au json format et l’en-tête Content-Type sera défini sur application/json. Voici un exemple de corps de requête contenant 5 requêtes inversées d’adresse de recherche :

{
    "batchItems": [
        {"query": "?query=48.858561,2.294911"},
        {"query": "?query=47.639765,-122.127896&radius=5000&limit=2"},
        {"query": "?query=47.621028,-122.348170"},
        {"query": "?query=43.722990,10.396695"},
        {"query": "?query=40.750958,-73.982336"}
    ]
}

Une requête inversée d’adresse de recherche dans un lot est simplement une URL partielle sans le protocole, l’URL de base, le chemin, la version de l’API et la clé d’abonnement. Il peut accepter n’importe quel paramètre d’URIinverse d’adresse de recherche pris en charge. Les valeurs de chaîne dans la requête inverse d’adresse de recherche doivent être correctement placées dans une séquence d’échappement (par exemple, « caractère doit être placé dans une séquence d’échappement avec \ ) et doivent également être correctement codées sur l’URL.

L’API asynchrone permet à l’appelant de traiter par lot jusqu’à 10 000 requêtes et de synchroniser l’API jusqu’à 100 requêtes, et le lot doit contenir au moins 1 requête.

Télécharger les résultats de lot asynchrones

Pour télécharger les résultats du lot asynchrone, vous allez envoyer une GET requête au point de terminaison de téléchargement par lots. Cette URL de téléchargement peut être obtenue à partir de l’en-tête Location d’une demande de lot réussie POST et se présente comme suit :

https://atlas.microsoft.com/search/address/reverse/batch/{batch-id}?api-version=1.0&subscription-key={subscription-key}

Voici la séquence classique d’opérations pour télécharger les résultats du lot :

1. Le client envoie une GET requête à l’aide de l’URL de téléchargement.

2. Le serveur répond avec l’une des opérations suivantes :

   HTTP 202 Accepted : la requête Batch a été acceptée, mais elle est toujours en cours de traitement. Réessayez dans un certain temps.

   HTTP 200 OK : requête Batch traitée avec succès. Le corps de la réponse contient tous les résultats du lot.

Modèle de réponse par lot

Le contenu des données retournées est similaire pour les demandes asynchrones et de synchronisation. Lors du téléchargement des résultats d’une demande de lot asynchrone, si le traitement du lot est terminé, le corps de la réponse contient la réponse par lot. Cette réponse par lot contient un summary composant qui indique qui totalRequests faisait partie de la demande de lot d’origine, c’est-à-dire successfulRequestsles requêtes qui ont été exécutées avec succès. La réponse par lot inclut également un batchItems tableau qui contient une réponse pour chaque requête dans la demande de lot. Contient batchItems les résultats exactement dans le même ordre que celui que les requêtes d’origine ont été envoyées dans la demande de lot. Chaque élément dans batchItems contient statusCode des champs et response . Chaque response dans batchItems est de l’un des types suivants :

• SearchAddressReverseResponse - Si la requête s’est terminée correctement.

• Error - Si la requête a échoué. La réponse contient un code et un message dans ce cas.

Voici un exemple de réponse par lot avec 2 réussites et 1 échec :

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 11
                },
                "addresses": [
                    {
                        "address": {
                            "country": "France",
                            "freeformAddress": "Avenue Anatole France, 75007 Paris"
                        },
                        "position": "48.858490,2.294820"
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "queryTime": 1
                },
                "addresses": [
                    {
                        "address": {
                            "country": "United States of America",
                            "freeformAddress": "157th Pl NE, Redmond WA 98052"
                        },
                        "position": "47.640470,-122.129430"
                    }
                ]
            }
        },
        {
            "statusCode": 400,
            "response":
            {
                "error":
                {
                    "code": "400 BadRequest",
                    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
                }
            }
        }
    ]
}

POST https://atlas.microsoft.com/search/address/reverse/batch/json?api-version=1.0

Paramètres URI

En-tête de la demande

Corps de la demande

Réponses

Sécurité

AADToken

Il s’agit des flux Microsoft Entra OAuth 2.0. Lorsqu’il est associé au contrôle d’accès en fonction du rôle Azure, il peut être utilisé pour contrôler l’accès à Azure Maps API REST. Les contrôles d’accès en fonction du rôle Azure sont utilisés pour désigner l’accès à un ou plusieurs Azure Maps compte de ressource ou sous-ressources. Tout utilisateur, groupe ou principal de service peut se voir accorder l’accès via un rôle intégré ou un rôle personnalisé composé d’une ou plusieurs autorisations pour Azure Maps API REST.

Pour implémenter des scénarios, nous vous recommandons d’afficher les concepts d’authentification. En résumé, cette définition de sécurité fournit une solution pour modéliser 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 qui est provisionnée lorsque vous créez un compte Azure Maps dans le Portail Azure ou à l’aide de PowerShell, cli, kits SDK Azure ou API REST.

Avec cette clé, n’importe quelle application peut accéder à toutes les API REST. En d’autres termes, cette clé peut être utilisée comme clé master dans le compte dans lequel elle est émise.

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

Type: apiKey
Dans: query

SAS Token

Il s’agit d’un jeton de signature d’accès partagé créé à partir de l’opération Répertorier les SAP sur la ressource Azure Maps via le plan de gestion Azure via Portail Azure, PowerShell, CLI, kits SDK Azure ou 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 à la ou les régions d’utilisation du 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 Map afin de limiter les abus de rendu et de renouveler régulièrement le jeton SAS.

Type: apiKey
Dans: header

Exemples

A Reverse Geocoding Batch API call containing 5 Reverse Geocoding API queries

POST https://atlas.microsoft.com/search/address/reverse/batch/json?api-version=1.0

{
  "batchItems": [
    {
      "query": "?query=48.858561,2.294911"
    },
    {
      "query": "?query=47.639765,-122.127896&radius=5000&limit=2"
    },
    {
      "query": "?query=47.621028,-122.348170"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "7",
              "routeNumbers": [],
              "streetName": "Avenue Anatole France",
              "streetNameAndNumber": "7 Avenue Anatole France",
              "countryCode": "FR",
              "countrySubdivisionCode": "Île-de-France",
              "countrySecondarySubdivision": "Paris",
              "municipality": "Paris",
              "postalCode": "75007",
              "municipalitySubdivision": "7ème Arrondissement",
              "country": "France",
              "countryCodeISO3": "FRA",
              "freeformAddress": "7 Avenue Anatole France, Paris, 75007",
              "boundingBox": {
                "northEast": "48.858321,2.295167",
                "southWest": "48.858136,2.295027",
                "entity": "position"
              }
            },
            "position": "48.858231,2.295089"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 8,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "routeNumbers": [],
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "municipality": "Redmond",
              "postalCode": "98052",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "Redmond, WA 98052",
              "boundingBox": {
                "northEast": "47.639765,-122.128661",
                "southWest": "47.639502,-122.129456",
                "entity": "position"
              },
              "countrySubdivisionName": "Washington"
            },
            "position": "47.639687,-122.128677"
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "queryTime": 19,
          "numResults": 1
        },
        "addresses": [
          {
            "address": {
              "streetNumber": "410",
              "routeNumbers": [],
              "streetName": "Thomas Street",
              "streetNameAndNumber": "410 Thomas Street",
              "countryCode": "US",
              "countrySubdivisionCode": "WA",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "municipality": "Seattle",
              "postalCode": "98109",
              "municipalitySubdivision": "Seattle, Lower Queen Anne",
              "country": "United States",
              "countryCodeISO3": "USA",
              "freeformAddress": "410 Thomas Street, Seattle, WA 98109",
              "boundingBox": {
                "northEast": "47.620954,-122.347601",
                "southWest": "47.620944,-122.348498",
                "entity": "position"
              },
              "extendedPostalCode": "981094621",
              "countrySubdivisionName": "Washington"
            },
            "position": "47.620945,-122.348175"
          }
        ]
      }
    }
  ]
}

Operation-Location: URL to download the results of the long-running batch request.

Définitions

Address

Adresse du résultat

AddressRanges

Décrit la plage d’adresses des deux côtés de la rue pour un résultat de recherche. Les coordonnées des emplacements de début et de fin de la plage d’adresses sont incluses.

BatchRequest

Ce type représente le corps de la demande pour le service Batch.

BatchRequestItem

Objet de requête Batch

BoundingBox

Fenêtre d’affichage qui couvre le résultat représenté par les coordonnées en haut à gauche et en bas à droite de la fenêtre d’affichage.

BoundingBoxCompassNotation

Cadre englobant de l’emplacement.

Brand

Marque associée au poI

Classification

Classification du poI retourné

ClassificationName

Nom de la classification

DataSources

Section facultative. Id de référence à utiliser avec l’API Obtenir Recherche Polygon.

Entity

Source du type d’entité du cadre englobant. Pour le géocodage inverse, cela est toujours égal à la position.

EntryPoint

Point d’entrée du poI retourné.

EntryPointType

Type de point d’entrée. La valeur peut être main ou mineure.

ErrorAdditionalInfo

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

ErrorDetail

Détail de l’erreur.

ErrorResponse

Réponse d’erreur

GeographicEntityType

Type d’entité Geography. Présente uniquement lorsque entityType a été demandé et est disponible.

Geometry

Informations sur la forme géométrique du résultat. Présent uniquement si type == Geography.

JsonFormat

Format souhaité de la réponse. Seul le format json est pris en charge.

LatLongPairAbbreviated

Emplacement représenté sous la forme d’une latitude et d’une longitude utilisant des noms courts « lat » & « lon ».

MatchType

Types de correspondance pour une opération de recherche d’adresse inverse.

OperatingHours

Heures d’ouverture d’un POI (Points d’intérêt).

OperatingHoursTime

Représente une date et une heure

OperatingHoursTimeRange

Plage horaire ouverte pour une journée

PointOfInterest

Détails des poI retournés, notamment des informations telles que le nom, le téléphone, l’adresse URL et les classifications.

PointOfInterestCategorySet

Catégorie POI

QueryType

Type de requête retourné : NEARBY ou NON_NEAR.

Response

Résultat de la requête. SearchAddressResult si la requête s’est terminée correctement, Sinon, ErrorResponse.

ReverseSearchAddressBatchItem

Élément retourné par Recherche’appel de service Address Reverse Batch.

ReverseSearchAddressBatchProcessResult

Cet objet est retourné à partir d’un appel de service de Recherche Address Reverse Batch réussi.

SearchAddressResultItem

Objet Result pour une réponse d’API Recherche.

SearchAddressResultType

Valeurs possibles :

• POI
• Rue
• Geography
• Adresse exacte
• Plage d’adresses
• Croisement

SearchSummary

Objet Summary pour une réponse d’API Recherche.

Summary

Résumé des résultats de la demande de lot