Referens för API för sökning efter lokala företag i Bing v7
Varning
Den 30 oktober 2020 flyttades Bing-sökning-API:erna från Azure AI-tjänster till Bing-sökning Services. Den här dokumentationen tillhandahålls endast som referens. Uppdaterad dokumentation finns i dokumentationen för API:et för Bing-sökning. Anvisningar om hur du skapar nya Azure-resurser för Bing-sökning finns i Skapa en Bing-sökning resurs via Azure Marketplace.
API:et för sökning efter lokala företag skickar en sökfråga till Bing för att få resultat som inkluderar restauranger, hotell eller andra lokala företag. För platser kan frågan ange namnet på det lokala företaget eller en kategori (till exempel restauranger nära mig). Entitetsresultat omfattar personer, platser eller saker. Platsen i det här sammanhanget är affärsentiteter, stater, länder/regioner osv.
Det här avsnittet innehåller teknisk information om svarsobjekten och de frågeparametrar och rubriker som påverkar sökresultaten. Exempel som visar hur du gör begäranden finns i Snabbstart för C#-snabbstart för lokal företagssökning eller Java-snabbstart för sökning i lokalt företag.
Information om rubriker som begäranden ska innehålla finns i Rubriker.
Information om frågeparametrar som begäranden ska innehålla finns i Frågeparametrar.
Information om JSON-objekten som svaret innehåller finns i Svarsobjekt.
Information om tillåten användning och visning av resultat finns i Använda och visa krav.
Slutpunkt
Om du vill begära lokala affärsresultat skickar du en GET-begäran till:
https://api.cognitive.microsoft.com/bing/v7.0/localbusinesses/search
Begäran måste använda HTTPS-protokollet.
Anteckning
Den maximala URL-längden är 2 048 tecken. För att säkerställa att URL-längden inte överskrider gränsen bör den maximala längden för dina frågeparametrar vara mindre än 1 500 tecken. Om URL:en överskrider 2 048 tecken returnerar servern 404 Hittades inte.
Sidhuvuden
Följande är de rubriker som en begäran och ett svar kan innehålla.
| Huvud | Description |
|---|---|
| Acceptera | Valfritt begärandehuvud. Standardmedietypen är application/json. Om du vill ange att svaret använder JSON-LD anger du accept-huvudet till application/ld+json. |
| Accept-Language | Valfritt begärandehuvud. En kommaavgränsad lista över språk som ska användas för användargränssnittssträngar. Listan är i fallande prioritetsordning. Mer information, bland annat om det förväntade formatet, finns i RFC2616. Det här huvudet och frågeparametern setLang är ömsesidigt uteslutande – ange inte båda. Om du anger huvudet måste du även ange frågeparametern cc. För att fastställa vilken marknad som resultat ska returneras för använder Bing det första språk som stöds på listan och kombinerar det med parametervärdet cc. Om listan inte innehåller något språk som stöds hittar Bing det närmaste språket och marknaden som har stöd för begäran, eller så använder Bing en aggregerad eller standardmarknad för resultatet. För att avgöra vilken marknad som används i Bing kan du gå till BingAPIs-Market-huvudet.Använd enbart det här huvudet och cc-frågeparametern om du anger flera språk. Annars kan du använda frågeparametrarna mkt och setLang.En användargränssnittssträng är en sträng som används som en etikett i ett användargränssnitt. Det finns några användargränssnittssträngar i JSON-svarsobjekt. Alla länkar till Bing.com-egenskaper i svarsobjekten använder det angivna språket. |
| BingAPIs-Market | Svarshuvud. Marknaden som används av begäran. Formuläret är <languageCode-countryCode<>>. Exempel: sv-SE. |
| BingAPIs-TraceId | Svarshuvud. ID för loggposten som innehåller information om begäran. När ett fel uppstår ska du avbilda detta ID. Om det inte går att fastställa och lösa problemet ska du ange ID:t tillsammans med annan information som du ger supportteamet. |
| Ocp-Apim-Subscription-Key | Begärandehuvud som krävs. Prenumerationsnyckeln som du fick när du registrerade dig för den här tjänsten i Azure AI-tjänster. |
| Pragma | Valfritt begärandehuvud Som standard returnerar Bing cachelagrat innehåll om det finns. Om du vill förhindra att Bing returnerar cachelagrat innehåll ska du ställa in huvudet Pragma på no-cache (till exempel Pragma: no-cache). |
| User-Agent | Valfritt begärandehuvud. Användaragenten som skapade begäran. Bing använder användaragenten för att ge mobila användare en optimerad upplevelse. Även om det är valfritt rekommenderar vi även att du alltid anger det här huvudet. Användaragenten ska vara samma sträng som alla vanliga webbläsare skickar. Information om användaragenter finns i RFC 2616. Här följer några exempel på användaragentsträngar.
|
| X-MSEdge-ClientID | Valfritt huvud för begäran och svar. Bing använder det här huvudet för att ge användarna konsekvent beteende i Bing API-anrop. Bing ger ofta förhandsversioner av nya funktioner och förbättringar och använder klient-ID som en nyckel för att tilldela trafik till olika förhandsversioner. Om du inte använder samma klient-ID för en användare vid flera förfrågningar kan sedan Bing tilldela användaren flera motstridiga förhandsversioner. Om du tilldelas flera motstridiga förhandsversioner kan det leda till en inkonsekvent användarupplevelse. Om till exempel den andra begäran har en annan förhandsversionstilldelning än den första kan upplevelsen vara oväntad. Bing kan också använda klient-ID för att skräddarsy webbresultatet för klient-ID:ts sökhistorik, vilket ger användaren en mer omfattande upplevelse. Bing använder också det här huvudet för att förbättra resultatets rangordning genom att analysera aktiviteten som genererats av ett klient-ID. Relevansförbättringarna kan ge bättre resultat som levereras av Bing-API: er, vilka i sin tur möjliggör högre klickfrekvens för API-konsumenten. Viktigt! Även om det är valfritt bör du överväga att använda det här huvudet som krävs. Bestående klient-ID för flera förfrågningar för samma slutanvändare och enhetskombination gör det möjligt 1) för API-konsumenten att få en konsekvent användarupplevelse och 2) att få högre klickfrekvens via resultat av högre kvalitet från Bing-API: er. Följande är de grundläggande användningsregler som gäller för det här huvudet.
Obs! Bing-svar kanske eller kanske inte omfattar det här huvudet. Om svaret innehåller det här huvudet ska du avbilda klient-ID:t och använda det för alla efterföljande Bing-begäranden för användaren på enheten. Obs! Om du inkluderar X-MSEdge-ClientID får du inte ta med cookies i begäran. |
| X-MSEdge-ClientIP | Valfritt begärandehuvud. Klientenhetens IPv4- eller IPv6-adress. IP-adressen används för att identifiera användarens plats. Bing använder platsinformationen för att fastställa SafeSearch-beteende. Obs!Även om det är valfritt rekommenderar vi att du alltid anger det här huvudet och huvudet X-Search-Location. Förvräng inte adressen (till exempel genom att ändra den sista oktetten till 0). Om adressresultatet förvillas på en plats som inte är i närheten av enhetens verkliga plats kan det leda till att Bing presenterar felaktiga resultat. |
| X-Search-Location | Valfritt begärandehuvud. En semikolonavgränsad lista med nyckel/värde-par som beskriver klientens geografiska plats. Bing använder platsinformationen till att fastställa ett säkert sökbeteende och returnera relevant lokalt innehåll. Ange nyckel/värde-par som <nyckel>:<värde>. Följande är de nycklar som används för att ange användarens plats.
OBSERVERA: Du uppmanas att alltid ange användarens geografiska plats. Det är särskilt viktigt att ange plats om klientens IP-adress inte exakt avspeglar användarens fysiska plats (till exempel om klienten använder VPN). För bästa resultat bör du inkludera det här huvudet och huvudet X-MSEdge-ClientIP, men du bör minst inkludera det här huvudet. |
Anteckning
Kom ihåg att användningsvillkoren kräver efterlevnad med alla tillämpliga lagar, inklusive lagar om användande av dessa huvud. I till exempel vissa jurisdiktioner, som Europa, finns det krav på att skaffa användarens medgivande innan du placerar vissa spårningsenheter på användarenheter.
Frågeparametrar
Begäran kan innehålla följande frågeparametrar. Se kolumnen Obligatorisk för obligatoriska parametrar. Du måste URL-koda frågeparametrarna.
| Name | Värde | Typ | Obligatorisk |
|---|---|---|---|
| Räkna | Antalet resultat som ska returneras, med början i det index som anges av parametern offset . |
Sträng | No |
| localCategories | Lista över alternativ som definierar sökning efter affärskategori. Se Sökning efter lokala företagskategorier | Sträng | No |
| mkt | Marknaden som resultatet kommer från. En lista över möjliga marknadsvärden finns i Marknadskoder. OBSERVERA: API:et för sökning efter lokala företag stöder för närvarande endast en-us-marknad och språk. |
Sträng | Yes |
| offset | Indexet för att starta resultat som anges av parametern count . |
Integer | No |
| F | Användarens sökterm. | Sträng | No |
| responseFormat | Medietypen som ska användas för svaret. Följande är möjliga skiftlägesokänsliga värden.
Standardvärdet är JSON. Information om JSON-objekten som svaret innehåller finns i Svarsobjekt. Om du anger JsonLd innehåller svarstexten JSON-LD-objekt som innehåller sökresultaten. Information om JSON-LD finns i JSON-LD. |
Sträng | No |
| safeSearch | Ett filter som används för att filtrera innehåll som är olämpligt för barn. Här följer de möjliga skiftlägeskänsliga filtervärdena.
Standardinställningen är Måttlig. OBSERVERA: Om begäran kommer från en marknad som Bings vuxenpolicy kräver som safeSearch är inställd på Strikt ignorerar safeSearch Bing värdet och använder Strict.Obs! Beroende på om du använder frågeoperator site: finns det en risk att svaret har innehåll som är olämpligt för barn oberoende av vad frågeparametern safeSearch är inställd på. Använd endast site: om du är medveten om innehållet på webbplatsen och ditt scenario tillåter möjligheten att det förekommer innehåll som är olämpligt för barn. |
Sträng | No |
| setLang | Språket som ska användas för användargränssnittssträngar. Ange språk med hjälp av den tvåstaviga språkkoden ISO 639-1. Språkkoden för engelska är till exempel EN. Standardvärdet är EN (engelska). Även om det är valfritt bör du alltid ange språket. Normalt anger du setLang på samma språk som anges av mkt om inte användaren vill att gränssnittets strängar ska visas på ett annat språk.Den här parametern och rubriken Accept-Language är ömsesidigt uteslutande – ange inte båda. En användargränssnittssträng är en sträng som används som en etikett i ett användargränssnitt. Det finns några användargränssnittssträngar i JSON-svarsobjekt. Alla länkar till Bing.com-egenskaper i svarsobjekten använder det angivna språket. |
Sträng | No |
Svarsobjekt
Följande är JSON-svarsobjekten som svaret kan innehålla. Om begäran lyckas är objektet på den översta nivån i svaret SearchResponse-objektet . Om begäran misslyckas är objektet på den översta nivån ErrorResponse-objektet .
| Objekt | Description |
|---|---|
| Plats | Definierar information om ett lokalt företag, till exempel en restaurang eller ett hotell. |
Fel
Definierar felet som inträffade.
| Element | Beskrivning | Typ |
|---|---|---|
| Koden | Felkoden som identifierar felkategorin. En lista över möjliga koder finns i Felkoder. | Sträng |
| Meddelande | En beskrivning av felet. | Sträng |
| moreDetails | En beskrivning som ger ytterligare information om felet. | Sträng |
| Parametern | Frågeparametern i begäran som orsakade felet. | Sträng |
| subCode | Felkoden som identifierar felet. Om code till exempel är InvalidRequest subCode kan det vara ParameterInvalid eller ParameterInvalidValue. |
Sträng |
| Värde | Frågeparameterns värde som inte var giltigt. | Sträng |
ErrorResponse
Det objekt på den översta nivån som svaret innehåller när begäran misslyckas.
| Name | Värde | Typ |
|---|---|---|
| _Typ | Typtips. | Sträng |
| Fel | En lista med fel som beskriver orsakerna till att begäran misslyckades. | Fel[] |
Licens
Definierar den licens under vilken texten eller fotot kan användas.
| Name | Värde | Typ |
|---|---|---|
| name | Namnet på licensen. | Sträng |
| url | URL:en till en webbplats där användaren kan få mer information om licensen. Använd namnet och URL:en för att skapa en hyperlänk. |
Sträng |
Länk
Definierar komponenterna i en hyperlänk.
| Name | Värde | Typ |
|---|---|---|
| _Typ | Typtips. | Sträng |
| text | Visningstexten. | Sträng |
| url | En URL. Använd URL:en och visa text för att skapa en hyperlänk. | Sträng |
Organisation
Definierar en utgivare.
Observera att en utgivare kan ange sitt namn eller sin webbplats eller båda.
| Name | Värde | Typ |
|---|---|---|
| name | Utgivarens namn. | Sträng |
| url | URL:en till utgivarens webbplats. Observera att utgivaren kanske inte tillhandahåller någon webbplats. |
Sträng |
Plats
Definierar information om ett lokalt företag, till exempel en restaurang eller ett hotell.
| Name | Värde | Typ |
|---|---|---|
| _Typ | Typtips, som kan vara inställt på något av följande:
|
Sträng |
| adress | Postadressen till den plats där entiteten finns. | PostalAddress |
| entityPresentationInfo | Ytterligare information om entiteten, till exempel tips som du kan använda för att fastställa entitetens typ. Till exempel om det är en restaurang eller ett hotell. Fältet entityScenario är inställt på ListItem. |
EntityPresentationInfo |
| name | Entitetens namn. | Sträng |
| telefon | Enhetens telefonnummer. | Sträng |
| url | URL:en till entitetens webbplats. Använd den här URL:en tillsammans med entitetens namn för att skapa en hyperlänk som när du klickar tar användaren till entitetens webbplats. |
Sträng |
| webSearchUrl | URL:en till Bings sökresultat för den här platsen. | Sträng |
QueryContext
Definierar frågekontexten som Bing använde för begäran.
| Element | Beskrivning | Typ |
|---|---|---|
| adultIntent | Ett booleskt värde som anger om den angivna frågan har en vuxet avsikt. Värdet är sant om frågan har en avsikt som är vuxet. annars falskt. | Boolesk |
| ändringOverrideQuery | Frågesträngen som ska användas för att tvinga Bing att använda den ursprungliga strängen. Om frågesträngen till exempel salingar nedåt, kommer åsidosättningsfrågesträngen att vara +saling downwind. Kom ihåg att koda frågesträngen som resulterar i %2Bsaling+downwind. Det här fältet inkluderas bara om den ursprungliga frågesträngen innehåller ett stavfel. |
Sträng |
| alteredQuery | Frågesträngen som används av Bing för att utföra frågan. Bing använder den ändrade frågesträngen om den ursprungliga frågesträngen innehöll stavfel. Om frågesträngen till exempel är saling downwindblir den ändrade frågesträngen sailing downwind.Det här fältet inkluderas bara om den ursprungliga frågesträngen innehåller ett stavfel. |
Sträng |
| askUserForLocation | Ett booleskt värde som anger om Bing kräver att användarens plats ger korrekta resultat. Om du har angett användarens plats med hjälp av rubrikerna X-MSEdge-ClientIP och X-Search-Location kan du ignorera det här fältet. För platsmedvetna frågor, till exempel "dagens väder" eller "restauranger nära mig" som behöver användarens plats för att ge korrekta resultat, är det här fältet inställt på sant. För platsmedvetna frågor som innehåller platsen (till exempel "Väder i Seattle" anges det här fältet till falskt. Det här fältet är också inställt på falskt för frågor som inte är platsmedvetna, till exempel "bästsäljare". |
Boolesk |
| originalQuery | Frågesträngen som anges i begäran. | Sträng |
Identifierbar
| Name | Värde | Typ |
|---|---|---|
| id | En resursidentifierare | Sträng |
RankingGroup
Definierar en sökresultatgrupp, till exempel huvudlinjen.
| Name | Värde | Typ |
|---|---|---|
| objekt | En lista med sökresultat som ska visas i gruppen. | RankingItem |
RankingItem
Definierar ett sökresultatobjekt som ska visas.
| Name | Värde | Typ |
|---|---|---|
| resultIndex | Ett nollbaserat index för objektet i svaret som ska visas. Om objektet inte innehåller det här fältet visar du alla objekt i svaret. Visa till exempel alla nyhetsartiklar i nyhetssvaret. | Integer |
| answerType | Svaret som innehåller objektet som ska visas. Till exempel Nyheter. Använd typen för att hitta svaret i SearchResponse-objektet. Typen är namnet på ett SearchResponse-fält. Använd dock bara svarstypen om det här objektet innehåller värdefältet. annars kan du ignorera det. |
Sträng |
| textualIndex | Indexet för svaret i textualAnswers som ska visas. | Osignerat heltal |
| värde | Det ID som identifierar antingen ett svar som ska visas eller ett objekt i ett svar som ska visas. Om ID:t identifierar ett svar visar du alla objekt i svaret. | Identifierbar |
RankingResponse
Definierar var innehållet på sökresultatsidan ska placeras och i vilken ordning.
SearchResponse
Definierar objektet på den översta nivån som svaret innehåller när begäran lyckas.
Observera att om tjänsten misstänker en Denial of Service-attack kommer begäran att lyckas (HTTP-statuskoden är 200 OK); Brödtexten i svaret är dock tom.
| Name | Värde | Typ |
|---|---|---|
| _Typ | Typtips, som är inställt på SearchResponse. | Sträng |
| placerar | En lista över entiteter som är relevanta för sökfrågan. | JSON-objekt |
| queryContext | Ett objekt som innehåller frågesträngen som Bing använde för begäran. Det här objektet innehåller frågesträngen som angetts av användaren. Den kan också innehålla en ändrad frågesträng som Bing använde för frågan om frågesträngen innehöll ett stavfel. |
QueryContext |
Felkoder
Följande är de möjliga HTTP-statuskoder som en begäran returnerar.
| Statuskod | Description |
|---|---|
| 200 | Åtgärden lyckades. |
| 400 | En av frågeparametrarna saknas eller är ogiltig. |
| 401 | Prenumerationsnyckeln saknas eller är inte giltig. |
| 403 | Användaren autentiseras (till exempel använde de en giltig prenumerationsnyckel) men de har inte behörighet till den begärda resursen. Bing kan också returnera den här statusen om anroparen överskred sina frågor per månadskvot. |
| 410 | Begäran använde HTTP i stället för HTTPS-protokollet. HTTPS är det enda protokoll som stöds. |
| 429 | Anroparen överskred sin kvot för frågor per sekund. |
| 500 | Oväntat serverfel. |
Om begäran misslyckas innehåller svaret ett ErrorResponse-objekt som innehåller en lista över felobjekt som beskriver vad som orsakade felet. Om felet är relaterat till en parameter identifierar fältet parameter den parameter som är problemet. Och om felet är relaterat till ett parametervärde value identifierar fältet det värde som inte är giltigt.
{
"_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."
}
]
}
Följande är möjliga felkods- och underfelskodvärden.
| Kod | Underkod | Description |
|---|---|---|
| ServerError | UnexpectedError ResourceError NotImplemented |
HTTP-statuskoden är 500. |
| InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Blockerad |
Bing returnerar InvalidRequest när någon del av begäran inte är giltig. Till exempel saknas en obligatorisk parameter eller så är ett parametervärde ogiltigt. Om felet är ParameterMissing eller ParameterInvalidValue är HTTP-statuskoden 400. Om du använder HTTP-protokollet i stället för HTTPS returnerar Bing HttpNotAllowed och HTTP-statuskoden är 410. |
| RateLimitExceeded | Inga underkoder | Bing returnerar RateLimitExceeded när du överskrider kvoten för frågor per sekund (QPS) eller frågor per månad (QPM). Om du överskrider QPS returnerar Bing HTTP-statuskod 429, och om du överskrider QPM returnerar Bing 403. |
| InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing returnerar InvalidAuthorization när Bing inte kan autentisera anroparen. Till exempel Ocp-Apim-Subscription-Key saknas rubriken eller så är prenumerationsnyckeln inte giltig.Redundans inträffar om du anger mer än en autentiseringsmetod. Om felet är InvalidAuthorization är HTTP-statuskoden 401. |
| InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
Bing returnerar InsufficientAuthorization när anroparen inte har behörighet att komma åt resursen. Detta kan inträffa om prenumerationsnyckeln har inaktiverats eller har upphört att gälla. Om felet är InsufficientAuthorization är HTTP-statuskoden 403. |