Search - Post Search Address Batch

Utilisez pour envoyer un lot de requêtes à l’API d’adresse Recherche dans une requête asynchrone unique.
L’API Post Search Address Batch est une requête HTTP POST qui envoie des lots de requêtes à Recherche API d’adresse dans un seul appel d’API synchrone. Vous pouvez appeler Recherche API Batch d’adresse pour s’exécuter 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 par lots légères. Lorsque le service reçoit une requête, il répond dès que les éléments de lot sont calculés et qu’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/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 s’exécuter dans 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 demande par lots asynchrone est une opération de longue durée. Voici une séquence classique d’opérations :

1. Le client envoie une demande de lot POST d’adresses Recherche à Azure Maps.

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

2. Le serveur répond avec l’un des éléments suivants :

   HTTP 202 Accepted : la demande par lots a été acceptée.

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

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 pour 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/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 par lot

Pour envoyer les requêtes d’adresse de recherche , vous allez utiliser une POST requête où 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 d’adresse de recherche :

{
    "batchItems": [
        {"query": "?query=400 Broad St, Seattle, WA 98109&limit=3"},
        {"query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"},
        {"query": "?query=350 5th Ave, New York, NY 10118&limit=1"},
        {"query": "?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000"},
        {"query": "?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1"}
    ]
}

Une requête d’adresse de recherche dans un lot n’est qu’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’URId’adresse de recherche pris en charge. Les valeurs de chaîne dans la requête d’adresse de recherche doivent être correctement placées dans une séquence d’échappement (par exemple, « le caractère doit être placé dans une séquence d’échappement avec \ ) et il doit également être correctement codé dans 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 devez 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/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’un des éléments suivants :

   HTTP 202 Accepted : la demande par lots a été acceptée, mais elle est toujours en cours de traitement. Réessayez dans un certain temps.

   HTTP 200 OK - Requête par lots 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 de données retourné 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 de lot contient un summary composant qui indique les totalRequests qui faisaient partie de la demande de lot d’origine et successfulRequestsc’est-à-dire les 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 de la demande de lot. batchItems contient les résultats exactement dans l’ordre 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 :

• SearchAddressResult - Si la requête s’est terminée avec succès.

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

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

{
    "summary": {
        "successfulRequests": 2,
        "totalRequests": 3
    },
    "batchItems": [
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "one microsoft way redmond wa 98052"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.63989,
                            "lon": -122.12509
                        }
                    }
                ]
            }
        },
        {
            "statusCode": 200,
            "response":
            {
                "summary": {
                    "query": "pike pl seattle wa 98101"
                },
                "results": [
                    {
                        "position": {
                            "lat": 47.60963,
                            "lon": -122.34215
                        }
                    }
                ]
            }
        },
        {
            "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/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 ressources 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, de l’interface CLI, des SDK Azure ou de l’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, notre recommandation est 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 List SAS 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 de grain 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, notre recommandation est 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 SAP.

Type: apiKey
Dans: header

Exemples

An Address Geocoding Batch API call containing 5 Address Geocoding API queries

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

{
  "batchItems": [
    {
      "query": "?query=400 Broad St, Seattle, WA 98109&limit=3"
    },
    {
      "query": "?query=One, Microsoft Way, Redmond, WA 98052&limit=3"
    },
    {
      "query": "?query=350 5th Ave, New York, NY 10118&limit=1"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 3,
    "totalRequests": 3
  },
  "batchItems": [
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "400 broad st seattle wa 98109",
          "queryType": "NON_NEAR",
          "queryTime": 127,
          "numResults": 3,
          "offset": 0,
          "totalResults": 9,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/20843845",
            "score": 11.966,
            "address": {
              "streetNumber": "400",
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union, Lower Queen Anne",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "400 Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62039,
              "lon": -122.34928
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.62129,
                "lon": -122.35061
              },
              "btmRightPoint": {
                "lat": 47.61949,
                "lon": -122.34795
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 47.61982,
                  "lon": -122.34886
                }
              }
            ]
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388442",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, South Lake Union",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109",
              "extendedPostalCode": "981094612",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA 98109",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.62001,
              "lon": -122.34843
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61965,
                "lon": -122.34761
              },
              "btmRightPoint": {
                "lat": 47.62066,
                "lon": -122.349
              }
            }
          },
          {
            "type": "Street",
            "id": "US/STR/p0/388680",
            "score": 10.225,
            "address": {
              "streetName": "Broad Street",
              "municipalitySubdivision": "Seattle, Belltown",
              "municipality": "Seattle",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle",
              "countrySubdivisionCode": "WA",
              "postalCode": "98109,98121",
              "extendedPostalCode": "981094991,981211117,981211237,981213206",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Broad Street, Seattle, WA",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.61691,
              "lon": -122.35251
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.61502,
                "lon": -122.35041
              },
              "btmRightPoint": {
                "lat": 47.61857,
                "lon": -122.35484
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "one microsoft way redmond wa 98052",
          "queryType": "NON_NEAR",
          "queryTime": 169,
          "numResults": 2,
          "offset": 0,
          "totalResults": 3292,
          "fuzzyLevel": 2
        },
        "results": [
          {
            "type": "Street",
            "id": "US/STR/p0/1692663",
            "score": 10.225,
            "address": {
              "streetName": "Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "extendedPostalCode": "980526399,980528300",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63989,
              "lon": -122.12509
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.63748,
                "lon": -122.12309
              },
              "btmRightPoint": {
                "lat": 47.64223,
                "lon": -122.13061
              }
            }
          },
          {
            "type": "Cross Street",
            "id": "US/XSTR/p1/4779971",
            "score": 8.506,
            "address": {
              "streetName": "Microsoft Way & 157th Avenue Northeast, Microsoft Way",
              "municipality": "Redmond",
              "countrySecondarySubdivision": "King",
              "countryTertiarySubdivision": "Seattle East",
              "countrySubdivisionCode": "WA",
              "postalCode": "98052",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "Microsoft Way & 157th Avenue Northeast, Redmond, WA 98052",
              "countrySubdivisionName": "Washington"
            },
            "position": {
              "lat": 47.63962,
              "lon": -122.13061
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 47.64052,
                "lon": -122.13194
              },
              "btmRightPoint": {
                "lat": 47.63872,
                "lon": -122.12928
              }
            }
          }
        ]
      }
    },
    {
      "statusCode": 200,
      "response": {
        "summary": {
          "query": "350 5th ave new york ny 10118",
          "queryType": "NON_NEAR",
          "queryTime": 233,
          "numResults": 1,
          "offset": 0,
          "totalResults": 8032,
          "fuzzyLevel": 1
        },
        "results": [
          {
            "type": "Point Address",
            "id": "US/PAD/p0/48052000",
            "score": 14.334,
            "address": {
              "streetNumber": "350",
              "streetName": "5th Avenue",
              "municipalitySubdivision": "New York, Midtown South",
              "municipality": "New York, Manhattan",
              "countrySecondarySubdivision": "New York",
              "countryTertiarySubdivision": "Manhattan",
              "countrySubdivisionCode": "NY",
              "postalCode": "10118",
              "extendedPostalCode": "1011800",
              "countryCode": "US",
              "country": "United States Of America",
              "countryCodeISO3": "USA",
              "freeformAddress": "350 5th Avenue, NYC, NY 10118",
              "countrySubdivisionName": "New York"
            },
            "position": {
              "lat": 40.74817,
              "lon": -73.985
            },
            "viewport": {
              "topLeftPoint": {
                "lat": 40.74907,
                "lon": -73.98619
              },
              "btmRightPoint": {
                "lat": 40.74727,
                "lon": -73.98381
              }
            },
            "entryPoints": [
              {
                "type": "main",
                "position": {
                  "lat": 40.74808,
                  "lon": -73.98482
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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, ErrorResponse sinon.

SearchAddressBatchItem

Élément retourné par Recherche appel de service d’adresse Batch.

SearchAddressBatchProcessResult

Cet objet est retourné à partir d’un appel de service Recherche Address 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