Informations de référence sur l’API Recherche d’entreprises locales Bing v7
Avertissement
Le 30 octobre 2020, les API de recherche Bing sont passées des services Azure AI aux services de recherche Bing. Cette documentation est fournie à des fins de référence uniquement. Pour accéder à la documentation mise à jour, consultez la documentation de l’API Recherche Bing. Pour obtenir des instructions sur la création de nouvelles ressources Azure pour Recherche Bing, consultez Créer une ressource Recherche Bing à l’aide de Place de marché Azure.
L’API Recherche d’entreprises locales envoie une requête de recherche à Bing pour obtenir des résultats sur les restaurants, les hôtels et d’autres entreprises locales. Pour trouver des lieux, la requête peut spécifier le nom de l’entreprise locale ou une catégorie (par exemple, les restaurants autour de moi). Les résultats d’entités incluent des personnes, des lieux ou d’autres éléments. Dans ce contexte, un lieu correspond à une entité de type entreprise, un État, un pays/région, etc.
Cette section donne des détails techniques sur les objets de réponse, les paramètres de la requête et les en-têtes qui affectent les résultats de recherche. Pour obtenir des exemples montrant comment effectuer des requêtes, voir Démarrage rapide C# sur la Recherche d’entreprises locales ou Démarrage rapide Java sur la Recherche d’entreprises locales.
Pour plus d’informations sur les en-têtes que doivent comporter les demandes, voir En-têtes.
Pour plus d’informations sur les paramètres de requête que doivent comporter les demandes, voir Paramètres de la requête.
Pour plus d’informations sur les objets JSON que comporte la réponse, voir Objets de la réponse.
Pour plus d’informations sur l’utilisation autorisée et l’affichage des résultats, voir Conditions d’utilisation et d’affichage.
Point de terminaison
Pour demander les résultats en matière d’entreprises locales, envoyez une demande GET à :
https://api.cognitive.microsoft.com/bing/v7.0/localbusinesses/search
La requête doit utiliser le protocole HTTPS.
Notes
La longueur maximale de l’URL est de 2 048 caractères. Pour que votre URL ne dépasse pas la limite, la longueur maximale de vos paramètres de requête doit être inférieure à 1 500 caractères. Si l’URL dépasse 2 048 caractères, le serveur retourne une erreur 404 (Introuvable).
headers
Voici les en-têtes possibles d’une demande et d’une réponse.
| En-tête | Description |
|---|---|
| Acceptation | En-tête de demande facultatif. Le type de média par défaut est application/json. Pour spécifier que la réponse utilise JSON-LD, donnez la valeur application/ld+json à l’en-tête Accept. |
| Accept-Language | En-tête de demande facultatif. Liste délimitée par des virgules des langues à utiliser pour les chaînes d’interface utilisateur. Elle est triée par ordre de préférence décroissant. Pour plus d’informations, notamment le format attendu, voir RFC2616. Cet en-tête et le paramètre de requête setLang s’excluent mutuellement ; ne spécifiez pas les deux. Si vous définissez cet en-tête, vous devrez également spécifier le paramètre de requête cc. Pour déterminer pour quel marché les résultats devront être retournés, Bing utilise la première langue prise en charge qu’il trouve dans la liste et la combine avec la valeur du paramètre cc. Si la liste ne comporte pas de langue prise en charge, Bing recherche la langue et le marché les plus proches qui prennent en charge la demande, ou utilise un marché agrégé ou par défaut pour les résultats. Pour identifier le marché utilisé par Bing, voir l’en-tête BingAPIs-Market.N’utilisez cet en-tête et le paramètre de requête cc que si vous spécifiez plusieurs langues. Sinon, utilisez les paramètres de requête mkt et setLang.Une chaîne d’interface utilisateur est une chaîne utilisée comme étiquette dans une interface utilisateur. Les objets de réponse JSON en comportent quelques-unes. Les liens vers les propriétés Bing.com dans les objets de la réponse s’appliquent à la langue spécifiée. |
| BingAPIs-Market | En-tête de réponse. Marché utilisé par la demande. Le format est <languageCode>-<countryCode>. Par exemple, en-US. |
| BingAPIs-TraceId | En-tête de réponse. ID de l’entrée du journal contenant les détails de la demande. Lorsqu’une erreur se produit, capturez cet ID. Si vous ne parvenez pas à identifier ou à résoudre le problème, précisez cet ID avec les autres informations envoyées à l’équipe de support. |
| Ocp-Apim-Subscription-Key | En-tête de demande requis. La clé d’abonnement que vous avez reçue lors de votre inscription à ce service dans Azure AI services. |
| Pragma | En-tête de demande facultatif. Par défaut, Bing retourne le contenu en cache, s’il est disponible. Pour éviter cela, définissez l’en-tête Pragma sur no-cache (par exemple, Pragma: no-cache). |
| User-Agent | En-tête de demande facultatif. Agent utilisateur à l’origine de la requête. Bing utilise l’agent utilisateur pour offrir une expérience optimisée aux utilisateurs mobiles. Nous vous conseillons de toujours indiquer cet en-tête, bien qu’il soit facultatif. L’agent utilisateur doit correspondre à la chaîne envoyée par n’importe quel navigateur couramment utilisé. Pour plus d’informations sur les agents utilisateurs, voir RFC 2616. Voici quelques exemples de chaînes de l’agent utilisateur.
|
| X-MSEdge-ClientID | En-tête de demande et de réponse facultatif. Bing utilise cet en-tête pour garantir aux utilisateurs un comportement cohérent d’un appel d’API Bing à l’autre. Bing propose souvent de nouvelles fonctionnalités et améliorations, et se sert de l’ID client comme d’une clé pour attribuer le trafic aux différentes versions d’évaluation. Si vous n’assignez pas le même ID client à un utilisateur d’une demande à l’autre, Bing est susceptible d’affecter cet utilisateur à plusieurs versions d’évaluation en conflit, ce qui risque de nuire à l’expérience utilisateur. Par exemple, si la deuxième demande comporte une attribution de version d’évaluation différente de la première, l’expérience se révélera peut-être inattendue. De même, Bing peut utiliser l’ID client pour personnaliser les résultats web d’après l’historique de recherche correspondant à cet ID et ainsi proposer à l’utilisateur une expérience plus riche. Bing utilise également cet en-tête pour aider à améliorer le classement des résultats en analysant l’activité générée par un ID client. L’amélioration de la pertinence permet d’obtenir des résultats de meilleure qualité de la part des API Bing et, en retour, des taux de clic plus élevés pour le consommateur des API. IMPORTANT : Il est vivement recommandé d’indiquer cet en-tête, bien qu’il soit facultatif. Grâce à la persistance de l’ID client dans plusieurs demandes pour une même combinaison appareil/utilisateur final, (1) le consommateur des API bénéficie d’une expérience utilisateur cohérente et (2) le taux de clic est plus élevé du fait des résultats de meilleure qualité provenant des API Bing. Voici les règles d’utilisation de base qui s’appliquent à cet en-tête.
REMARQUE : Les réponses de Bing ne comportent pas forcément cet en-tête. Si elles l’incluent, capturez l’ID client et utilisez-le pour toutes les demandes Bing suivantes concernant l’utilisateur sur cet appareil. REMARQUE : Si vous insérez l’en-tête X-MSEdge-ClientID, n’incluez pas les cookies dans la requête. |
| X-MSEdge-ClientIP | En-tête de demande facultatif. Adresse IPv4 ou IPv6 de l’appareil client. L’adresse IP est utilisée pour découvrir l’emplacement de l’utilisateur. Bing utilise les informations de localisation pour déterminer le comportement de recherche approprié. REMARQUE : Nous vous conseillons de toujours indiquer cet en-tête et l’en-tête X-Search-Location, bien qu’ils soient facultatifs. N’obfusquez pas l’adresse (par exemple, en remplaçant le dernier octet par 0). Cela aurait pour effet d’éloigner la localisation de l’emplacement réel de l’appareil, ce qui pourrait conduire Bing à retourner des résultats erronés. |
| X-Search-Location | En-tête de demande facultatif. Liste délimitée par des points-virgules de paires clé/valeur qui décrivent la situation géographique du client. Bing utilise les informations de localisation pour déterminer le comportement de recherche approprié et retourner le contenu local pertinent. Spécifiez la paire clé/valeur sous la forme <clé>:<valeur>. Voici les clés permettant de spécifier l’emplacement de l’utilisateur.
REMARQUE : Nous vous conseillons de toujours indiquer la situation géographique de l’utilisateur, bien qu’elle soit facultative. C’est particulièrement important si l’adresse IP du client ne reflète pas exactement l’emplacement physique de l’utilisateur (par exemple, si le client utilise un VPN). Pour des résultats optimaux, précisez cet en-tête et l’en-tête X-MSEdge-ClientIP ; au minimum, indiquez cet en-tête. |
Notes
N’oubliez pas que les conditions d’utilisation imposent le respect de toutes les lois en vigueur, y compris en ce qui concerne l’utilisation de ces en-têtes. Par exemple, dans certaines juridictions, comme en Europe, il faut obtenir le consentement de l’utilisateur pour pouvoir placer certains dispositifs de suivi sur les appareils des utilisateurs.
Paramètres de requête
La demande peut comporter les paramètres de requête suivants. Consultez la colonne Requis pour savoir lesquels sont obligatoires. Vous devez encoder les paramètres de requête au format URL.
| Nom | Valeur | Type | Obligatoire |
|---|---|---|---|
| count | Nombre de résultats à retourner, en commençant par l’index spécifié par le paramètre offset. |
String | Non |
| localCategories | Liste des options qui définissent la recherche par catégorie d’entreprise. Voir Recherche par catégories d’entreprises locales. | String | Non |
| mkt | Marché d’où proviennent les résultats. Pour connaître la liste des valeurs de marché possibles, voir Codes de marché. REMARQUE : Actuellement, l’API Recherche d’entreprises locales ne prend en charge que le marché et la langue en-us. |
String | Oui |
| offset | Index de début des résultats spécifiés par le paramètre count. |
Integer | Non |
| q | Critère de recherche de l’utilisateur. | String | Non |
| responseFormat | Type de média à utiliser pour la réponse. Voici les valeurs possibles. Elles ne sont pas sensibles à la casse.
La valeur par défaut est JSON. Pour plus d’informations sur les objets JSON que contient la réponse, voir Objets de la réponse. Si vous spécifiez JsonLd, le corps de la réponse comporte les objets JSON-LD contenant les résultats de la recherche. Pour plus d’informations sur la spécification JSON-LD, voir JSON-LD. |
String | Non |
| safeSearch | Filtre utilisé pour filtrer le contenu pour adultes. Voici les valeurs possibles. Elles ne sont pas sensibles à la casse.
La valeur par défaut est Modéré. REMARQUE : Si la demande provient d’un marché où la stratégie de Bing en matière de contenu pour adultes exige que safeSearch ait la valeur Strict, Bing ignore la valeur safeSearch et utilise Strict.REMARQUE : Si vous utilisez l’opérateur de requête site:, il est possible que la réponse présente du contenu pour adultes, et ce quel que soit le paramètre de requête safeSearch défini. N’utilisez site: que si vous connaissez le contenu du site et si votre scénario accepte le contenu pour adultes. |
String | Non |
| setLang | Langue à utiliser pour les chaînes de l’interface utilisateur. Spécifiez la langue en utilisant le code de langue ISO 639-1 à deux lettres. Par exemple, celui de l’anglais est EN. La valeur par défaut est EN (anglais). Nous vous conseillons de toujours indiquer la langue, bien qu’elle soit facultative. En général, on définit setLang sur la langue spécifiée par mkt, sauf si l’utilisateur souhaite que les chaînes de l’interface utilisateur soient affichées dans une autre langue.Ce paramètre et l’en-tête Accept-Language s’excluent mutuellement ; ne spécifiez pas les deux. Une chaîne d’interface utilisateur est une chaîne utilisée comme étiquette dans une interface utilisateur. Les objets de réponse JSON en comportent quelques-unes. En outre, les liens vers les propriétés Bing.com dans les objets de la réponse s’appliquent à la langue spécifiée. |
String | Non |
Objets de la réponse
Voici les objets de réponse JSON que peut inclure la réponse. Si la demande aboutit, l’objet de niveau supérieur dans la réponse est l’objet SearchResponse. Si la demande échoue, l’objet de niveau supérieur est l’objet ErrorResponse.
| Object | Description |
|---|---|
| Place | Informations relatives à une entreprise locale, comme un restaurant ou un hôtel. |
Error
Définit l’erreur qui s’est produite.
| Élément | Description | Type |
|---|---|---|
| code | Code d’erreur identifiant la catégorie de l’erreur. Pour connaître la liste des codes possibles, voir Codes d’erreur. | String |
| message | Description de l’erreur. | String |
| moreDetails | Description de l’erreur comportant des informations supplémentaires. | String |
| parameter | Paramètre de requête de la demande ayant provoqué l’erreur. | String |
| subCode | Code identifiant l’erreur. Par exemple, si code est InvalidRequest, subCode peut être ParameterInvalid ou ParameterInvalidValue. |
String |
| value | Valeur du paramètre de requête qui n’était pas valide. | String |
ErrorResponse
Objet de niveau supérieur figurant dans la réponse en cas d’échec de la demande.
| Nom | Valeur | Type |
|---|---|---|
| _type | Indicateur de type. | String |
| errors | Liste des erreurs qui décrivent les raisons pour lesquelles la demande a échoué. | Error[] |
Licence
Définit la licence sous laquelle il est possible d’utiliser le texte ou la photo.
| Nom | Valeur | Type |
|---|---|---|
| name | Nom de la licence. | String |
| url | URL vers un site web sur lequel l’utilisateur trouvera plus d’informations sur la licence. Utilisez le nom et l’URL pour créer un lien hypertexte. |
String |
Lien
Définit les composants d’un lien hypertexte.
| Nom | Valeur | Type |
|---|---|---|
| _type | Indicateur de type. | String |
| text | Texte d’affichage. | String |
| url | URL. Utilisez l’URL et le texte d’affichage pour créer un lien hypertexte. | String |
Organisation
Définit un éditeur.
Notez qu’un éditeur peut indiquer son nom, son site web ou les deux.
| Nom | Valeur | Type |
|---|---|---|
| name | Nom de l’éditeur. | String |
| url | URL du site web de l’éditeur. Notez que l’éditeur peut ne pas indiquer de site web. |
String |
Emplacement
Informations relatives à une entreprise locale, comme un restaurant ou un hôtel.
| Nom | Valeur | Type |
|---|---|---|
| _type | Indicateur de type, qui peut avoir les valeurs suivantes :
|
String |
| address | Adresse postale où se trouve l’entité. | PostalAddress |
| entityPresentationInfo | Informations supplémentaires sur l’entité (par exemple, indicateurs permettant de déterminer le type de l’entité : restaurant, hôtel, etc.). Le champ entityScenario est défini sur ListItem. |
EntityPresentationInfo |
| name | Nom de l’entité. | String |
| telephone | Numéro de téléphone de l’entité. | String |
| url | URL du site web de l’entité. Utilisez-la avec le nom de l’entité pour créer un lien hypertexte qui amène l’utilisateur sur le site web de l’entité. |
String |
| webSearchUrl | URL des résultats de recherche de Bing sur ce lieu. | String |
QueryContext
Définit le contexte de requête utilisé par Bing pour la demande.
| Élément | Description | Type |
|---|---|---|
| adultIntent | Valeur booléenne qui indique si la requête spécifiée est destinée à des adultes. La valeur est true si c’est le cas, false sinon. | Boolean |
| alterationOverrideQuery | Chaîne de requête à utiliser pour forcer Bing à utiliser la chaîne d’origine. Par exemple, si la chaîne de requête est saling downwind, la chaîne de requête de remplacement sera +saling downwind. N’oubliez pas d’encoder la chaîne de requête, ce qui donne %2Bsaling+downwind. Ce champ n’est précisé que si la chaîne de requête d’origine contient une faute d’orthographe. |
String |
| alteredQuery | Chaîne de requête utilisée par Bing pour exécuter la requête. Bing utilise la chaîne de requête modifiée si la chaîne de requête d’origine contenait des fautes d’orthographe. Par exemple, si la chaîne de requête est saling downwind, la chaîne de requête modifiée sera sailing downwind.Ce champ n’est précisé que si la chaîne de requête d’origine contient une faute d’orthographe. |
String |
| askUserForLocation | Valeur booléenne qui indique si Bing exige que l’emplacement de l’utilisateur donne des résultats précis. Si vous avez spécifié l’emplacement de l’utilisateur à l’aide des en-têtes X-MSEdge-ClientIP et X-Search-Location, vous pouvez ignorer ce champ. Dans le cas des requêtes pour lesquelles l’emplacement de l’utilisateur doit fournir des résultats précis, comme « météo du jour » ou « restaurants proches », ce champ est défini sur true. Dans le cas des requêtes qui précisent l’emplacement (par exemple, « météo Seattle »), ce champ est défini sur false. Ce champ est également défini sur false pour les requêtes qui ne dépendent pas de la localisation, comme « meilleurs ventes ». |
Boolean |
| originalQuery | Chaîne de requête telle que spécifiée dans la demande. | String |
Identifiable
| Nom | Valeur | Type |
|---|---|---|
| id | Identificateur de ressource. | String |
RankingGroup
Définit un groupe de résultats de la recherche, par exemple, mainline.
| Nom | Valeur | Type |
|---|---|---|
| items | Liste de résultats de la recherche à afficher dans le groupe. | RankingItem |
RankingItem
Définit un élément de résultat de recherche à afficher.
| Nom | Valeur | Type |
|---|---|---|
| resultIndex | Index base zéro de l’élément de la réponse à afficher. Si l’élément ne comporte pas ce champ, affiche tous les éléments de la réponse. Par exemple, affiche tous les articles dans la réponse Actualités. | Integer |
| answerType | Réponse qui contient l’élément à afficher. Par exemple, Actualités. Utilisez le type pour trouver la réponse dans l’objet SearchResponse. Le type est le nom d’un champ SearchResponse. Toutefois, n’utilisez le type de réponse que si cet objet inclut le champ de valeur ; sinon, ignorez-le. |
String |
| textualIndex | Index de la réponse dans textualAnswers à afficher. | Entier non signé |
| value | ID qui identifie une réponse ou un élément de réponse à afficher. Si l’ID identifie une réponse, affiche tous les éléments de la réponse. | Identifiable |
RankingResponse
Définit où le contenu doit être placé sur la page de résultats de la recherche et dans quel ordre.
SearchResponse
Définit l’objet de niveau supérieur figurant dans la réponse en cas de réussite de la demande.
Notez que, si le service suspecte une attaque par déni de service, la demande réussira (le code d’état HTTP est 200 OK) ; toutefois, le corps de la réponse sera vide.
| Nom | Valeur | Type |
|---|---|---|
| _type | Indicateur de type, défini sur SearchResponse. | String |
| places | Liste d’entités pertinentes pour la requête de recherche. | Objet JSON |
| queryContext | Objet contenant la chaîne de requête utilisée par Bing pour la demande. Il comporte la chaîne de requête entrée par l’utilisateur. La chaîne de requête utilisée par Bing pour la requête peut également être une chaîne de requête modifiée, s’il y avait une faute d’orthographe dans la chaîne de requête. |
QueryContext |
Codes d’erreur
Voici les codes d’état HTTP qu’une demande peut retourner.
| Code d’état | Description |
|---|---|
| 200 | Réussite. |
| 400 | L’un des paramètres de requête est manquant ou non valide. |
| 401 | La clé d’abonnement est manquante ou non valide. |
| 403 | L’utilisateur est authentifié (par exemple, il a utilisé une clé d’abonnement valide), mais il n’est pas autorisé à accéder à la ressource demandée. Bing peut également retourner cet état si l’appelant a dépassé son quota mensuel de requêtes. |
| 410 | La demande a utilisé le protocole HTTP au lieu du protocole HTTPS. HTTPS est le seul protocole pris en charge. |
| 429 | L’appelant a dépassé son quota de requêtes par seconde. |
| 500 | Événement serveur inattendu. |
Si la demande échoue, la réponse comporte un objet ErrorResponse qui contient une liste d’objets Error décrivant l’origine de l’erreur. Si l’erreur est liée à un paramètre, le champ parameter identifie celui qui pose problème. De même, si l’erreur est liée à une valeur de paramètre, le champ value identifie la valeur non valide.
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidRequest",
"subCode": "ParameterMissing",
"message": "Required parameter is missing.",
"parameter": "q"
}
]
}
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidAuthorization",
"subCode": "AuthorizationMissing",
"message": "Authorization is required.",
"moreDetails": "Subscription key is not recognized."
}
]
}
Voici les valeurs possibles de code d’erreur et de sous-code d’erreur.
| Code | SubCode | Description |
|---|---|---|
| ServerError | UnexpectedError ResourceError NotImplemented |
Le code d’état HTTP est 500. |
| InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Bloqué |
Bing retourne InvalidRequest à chaque fois que la demande comporte une partie non valide. Par exemple, un paramètre obligatoire est manquant ou une valeur de paramètre n’est pas valide. Si l’erreur est ParameterMissing ou ParameterInvalidValue, le code d’état HTTP est 400. Si vous utilisez le protocole HTTP au lieu du protocole HTTPS, Bing retourne HttpNotAllowed, et le code d’état HTTP est 410. |
| RateLimitExceeded | Aucun sous-code | Bing retourne RateLimitExceeded chaque fois que vous dépassez votre quota de requêtes par seconde (QPS) ou par mois (QPM). Si vous dépassez votre QPS, Bing retourne le code d’état HTTP 429 ; si vous dépassez votre QPM, Bing retourne le code d’état 403. |
| InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing retourne InvalidAuthorization s’il ne parvient pas à identifier l’appelant. Par exemple, l’en-tête Ocp-Apim-Subscription-Key est manquant ou la clé d’abonnement n’est pas valide.Il y a redondance si plusieurs méthodes d’authentification sont spécifiées. Si l’erreur est InvalidAuthorization, le code d’état HTTP est 401. |
| InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
Bing retourne InsufficientAuthorization lorsque l’appelant n’est pas autorisé à accéder à la ressource. Cela peut se produire si la clé d’abonnement a été désactivée ou a expiré. Si l’erreur est InsufficientAuthorization, le code d’état HTTP est 403. |