1package websearch 2 3// Copyright (c) Microsoft and contributors. All rights reserved. 4// 5// Licensed under the Apache License, Version 2.0 (the "License"); 6// you may not use this file except in compliance with the License. 7// You may obtain a copy of the License at 8// http://www.apache.org/licenses/LICENSE-2.0 9// 10// Unless required by applicable law or agreed to in writing, software 11// distributed under the License is distributed on an "AS IS" BASIS, 12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13// 14// See the License for the specific language governing permissions and 15// limitations under the License. 16// 17// Code generated by Microsoft (R) AutoRest Code Generator. 18// Changes may cause incorrect behavior and will be lost if the code is regenerated. 19 20import ( 21 "context" 22 "github.com/Azure/go-autorest/autorest" 23 "github.com/Azure/go-autorest/autorest/azure" 24 "github.com/Azure/go-autorest/tracing" 25 "net/http" 26) 27 28// WebClient is the the Web Search API lets you send a search query to Bing and get back search results that include 29// links to webpages, images, and more. 30type WebClient struct { 31 BaseClient 32} 33 34// NewWebClient creates an instance of the WebClient client. 35func NewWebClient() WebClient { 36 return WebClient{New()} 37} 38 39// Search sends the search request. 40// Parameters: 41// query - the user's search query term. The term may not be empty. The term may contain Bing Advanced 42// Operators. For example, to limit results to a specific domain, use the site: operator. 43// acceptLanguage - a comma-delimited list of one or more languages to use for user interface strings. The list 44// is in decreasing order of preference. For additional information, including expected format, see 45// [RFC2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). This header and the setLang query 46// parameter are mutually exclusive; do not specify both. If you set this header, you must also specify the cc 47// query parameter. Bing will use the first supported language it finds from the list, and combine that 48// language with the cc parameter value to determine the market to return results for. If the list does not 49// include a supported language, Bing will find the closest language and market that supports the request, and 50// may use an aggregated or default market for the results instead of a specified one. You should use this 51// header and the cc query parameter only if you specify multiple languages; otherwise, you should use the mkt 52// and setLang query parameters. A user interface string is a string that's used as a label in a user 53// interface. There are very few user interface strings in the JSON response objects. Any links in the response 54// objects to Bing.com properties will apply the specified language. 55// pragma - by default, Bing returns cached content, if available. To prevent Bing from returning cached 56// content, set the Pragma header to no-cache (for example, Pragma: no-cache). 57// userAgent - the user agent originating the request. Bing uses the user agent to provide mobile users with an 58// optimized experience. Although optional, you are strongly encouraged to always specify this header. The 59// user-agent should be the same string that any commonly used browser would send. For information about user 60// agents, see [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). 61// clientID - bing uses this header to provide users with consistent behavior across Bing API calls. Bing often 62// flights new features and improvements, and it uses the client ID as a key for assigning traffic on different 63// flights. If you do not use the same client ID for a user across multiple requests, then Bing may assign the 64// user to multiple conflicting flights. Being assigned to multiple conflicting flights can lead to an 65// inconsistent user experience. For example, if the second request has a different flight assignment than the 66// first, the experience may be unexpected. Also, Bing can use the client ID to tailor web results to that 67// client ID’s search history, providing a richer experience for the user. Bing also uses this header to help 68// improve result rankings by analyzing the activity generated by a client ID. The relevance improvements help 69// with better quality of results delivered by Bing APIs and in turn enables higher click-through rates for the 70// API consumer. IMPORTANT: Although optional, you should consider this header required. Persisting the client 71// ID across multiple requests for the same end user and device combination enables 1) the API consumer to 72// receive a consistent user experience, and 2) higher click-through rates via better quality of results from 73// the Bing APIs. Each user that uses your application on the device must have a unique, Bing generated client 74// ID. If you do not include this header in the request, Bing generates an ID and returns it in the 75// X-MSEdge-ClientID response header. The only time that you should NOT include this header in a request is the 76// first time the user uses your app on that device. Use the client ID for each Bing API request that your app 77// makes for this user on the device. Persist the client ID. To persist the ID in a browser app, use a 78// persistent HTTP cookie to ensure the ID is used across all sessions. Do not use a session cookie. For other 79// apps such as mobile apps, use the device's persistent storage to persist the ID. The next time the user uses 80// your app on that device, get the client ID that you persisted. Bing responses may or may not include this 81// header. If the response includes this header, capture the client ID and use it for all subsequent Bing 82// requests for the user on that device. If you include the X-MSEdge-ClientID, you must not include cookies in 83// the request. 84// clientIP - the IPv4 or IPv6 address of the client device. The IP address is used to discover the user's 85// location. Bing uses the location information to determine safe search behavior. Although optional, you are 86// encouraged to always specify this header and the X-Search-Location header. Do not obfuscate the address (for 87// example, by changing the last octet to 0). Obfuscating the address results in the location not being 88// anywhere near the device's actual location, which may result in Bing serving erroneous results. 89// location - a semicolon-delimited list of key/value pairs that describe the client's geographical location. 90// Bing uses the location information to determine safe search behavior and to return relevant local content. 91// Specify the key/value pair as <key>:<value>. The following are the keys that you use to specify the user's 92// location. lat (required): The latitude of the client's location, in degrees. The latitude must be greater 93// than or equal to -90.0 and less than or equal to +90.0. Negative values indicate southern latitudes and 94// positive values indicate northern latitudes. long (required): The longitude of the client's location, in 95// degrees. The longitude must be greater than or equal to -180.0 and less than or equal to +180.0. Negative 96// values indicate western longitudes and positive values indicate eastern longitudes. re (required): The 97// radius, in meters, which specifies the horizontal accuracy of the coordinates. Pass the value returned by 98// the device's location service. Typical values might be 22m for GPS/Wi-Fi, 380m for cell tower triangulation, 99// and 18,000m for reverse IP lookup. ts (optional): The UTC UNIX timestamp of when the client was at the 100// location. (The UNIX timestamp is the number of seconds since January 1, 1970.) head (optional): The client's 101// relative heading or direction of travel. Specify the direction of travel as degrees from 0 through 360, 102// counting clockwise relative to true north. Specify this key only if the sp key is nonzero. sp (optional): 103// The horizontal velocity (speed), in meters per second, that the client device is traveling. alt (optional): 104// The altitude of the client device, in meters. are (optional): The radius, in meters, that specifies the 105// vertical accuracy of the coordinates. Specify this key only if you specify the alt key. Although many of the 106// keys are optional, the more information that you provide, the more accurate the location results are. 107// Although optional, you are encouraged to always specify the user's geographical location. Providing the 108// location is especially important if the client's IP address does not accurately reflect the user's physical 109// location (for example, if the client uses VPN). For optimal results, you should include this header and the 110// X-MSEdge-ClientIP header, but at a minimum, you should include this header. 111// answerCount - the number of answers that you want the response to include. The answers that Bing returns are 112// based on ranking. For example, if Bing returns webpages, images, videos, and relatedSearches for a request 113// and you set this parameter to two (2), the response includes webpages and images.If you included the 114// responseFilter query parameter in the same request and set it to webpages and news, the response would 115// include only webpages. 116// countryCode - a 2-character country code of the country where the results come from. This API supports only 117// the United States market. If you specify this query parameter, it must be set to us. If you set this 118// parameter, you must also specify the Accept-Language header. Bing uses the first supported language it finds 119// from the languages list, and combine that language with the country code that you specify to determine the 120// market to return results for. If the languages list does not include a supported language, Bing finds the 121// closest language and market that supports the request, or it may use an aggregated or default market for the 122// results instead of a specified one. You should use this query parameter and the Accept-Language query 123// parameter only if you specify multiple languages; otherwise, you should use the mkt and setLang query 124// parameters. This parameter and the mkt query parameter are mutually exclusive—do not specify both. 125// count - the number of search results to return in the response. The default is 10 and the maximum value is 126// 50. The actual number delivered may be less than requested.Use this parameter along with the offset 127// parameter to page results.For example, if your user interface displays 10 search results per page, set count 128// to 10 and offset to 0 to get the first page of results. For each subsequent page, increment offset by 10 129// (for example, 0, 10, 20). It is possible for multiple pages to include some overlap in results. 130// freshness - filter search results by the following age values: Day—Return webpages that Bing discovered 131// within the last 24 hours. Week—Return webpages that Bing discovered within the last 7 days. Month—Return 132// webpages that discovered within the last 30 days. This filter applies only to webpage results and not to the 133// other results such as news and images. 134// market - the market where the results come from. Typically, mkt is the country where the user is making the 135// request from. However, it could be a different country if the user is not located in a country where Bing 136// delivers results. The market must be in the form <language code>-<country code>. For example, en-US. The 137// string is case insensitive. If known, you are encouraged to always specify the market. Specifying the market 138// helps Bing route the request and return an appropriate and optimal response. If you specify a market that is 139// not listed in Market Codes, Bing uses a best fit market code based on an internal mapping that is subject to 140// change. This parameter and the cc query parameter are mutually exclusive—do not specify both. 141// offset - the zero-based offset that indicates the number of search results to skip before returning results. 142// The default is 0. The offset should be less than (totalEstimatedMatches - count). Use this parameter along 143// with the count parameter to page results. For example, if your user interface displays 10 search results per 144// page, set count to 10 and offset to 0 to get the first page of results. For each subsequent page, increment 145// offset by 10 (for example, 0, 10, 20). it is possible for multiple pages to include some overlap in results. 146// promote - a comma-delimited list of answers that you want the response to include regardless of their 147// ranking. For example, if you set answerCount) to two (2) so Bing returns the top two ranked answers, but you 148// also want the response to include news, you'd set promote to news. If the top ranked answers are webpages, 149// images, videos, and relatedSearches, the response includes webpages and images because news is not a ranked 150// answer. But if you set promote to video, Bing would promote the video answer into the response and return 151// webpages, images, and videos. The answers that you want to promote do not count against the answerCount 152// limit. For example, if the ranked answers are news, images, and videos, and you set answerCount to 1 and 153// promote to news, the response contains news and images. Or, if the ranked answers are videos, images, and 154// news, the response contains videos and news. Possible values are Computation, Images, News, RelatedSearches, 155// SpellSuggestions, TimeZone, Videos, Webpages. Use only if you specify answerCount. 156// responseFilter - a comma-delimited list of answers to include in the response. If you do not specify this 157// parameter, the response includes all search answers for which there's relevant data. Possible filter values 158// are Computation, Images, News, RelatedSearches, SpellSuggestions, TimeZone, Videos, Webpages. Although you 159// may use this filter to get a single answer, you should instead use the answer-specific endpoint in order to 160// get richer results. For example, to receive only images, send the request to one of the Image Search API 161// endpoints. The RelatedSearches and SpellSuggestions answers do not support a separate endpoint like the 162// Image Search API does (only the Web Search API returns them). To include answers that would otherwise be 163// excluded because of ranking, see the promote query parameter. 164// safeSearch - a filter used to filter adult content. Off: Return webpages with adult text, images, or videos. 165// Moderate: Return webpages with adult text, but not adult images or videos. Strict: Do not return webpages 166// with adult text, images, or videos. The default is Moderate. If the request comes from a market that Bing's 167// adult policy requires that safeSearch is set to Strict, Bing ignores the safeSearch value and uses Strict. 168// If you use the site: query operator, there is the chance that the response may contain adult content 169// regardless of what the safeSearch query parameter is set to. Use site: only if you are aware of the content 170// on the site and your scenario supports the possibility of adult content. 171// setLang - the language to use for user interface strings. Specify the language using the ISO 639-1 2-letter 172// language code. For example, the language code for English is EN. The default is EN (English). Although 173// optional, you should always specify the language. Typically, you set setLang to the same language specified 174// by mkt unless the user wants the user interface strings displayed in a different language. This parameter 175// and the Accept-Language header are mutually exclusive; do not specify both. A user interface string is a 176// string that's used as a label in a user interface. There are few user interface strings in the JSON response 177// objects. Also, any links to Bing.com properties in the response objects apply the specified language. 178// textDecorations - a Boolean value that determines whether display strings should contain decoration markers 179// such as hit highlighting characters. If true, the strings may include markers. The default is false. To 180// specify whether to use Unicode characters or HTML tags as the markers, see the textFormat query parameter. 181// textFormat - the type of markers to use for text decorations (see the textDecorations query parameter). 182// Possible values are Raw—Use Unicode characters to mark content that needs special formatting. The Unicode 183// characters are in the range E000 through E019. For example, Bing uses E000 and E001 to mark the beginning 184// and end of query terms for hit highlighting. HTML—Use HTML tags to mark content that needs special 185// formatting. For example, use <b> tags to highlight query terms in display strings. The default is Raw. For 186// display strings that contain escapable HTML characters such as <, >, and &, if textFormat is set to HTML, 187// Bing escapes the characters as appropriate (for example, < is escaped to <). 188func (client WebClient) Search(ctx context.Context, query string, acceptLanguage string, pragma string, userAgent string, clientID string, clientIP string, location string, answerCount *int32, countryCode string, count *int32, freshness Freshness, market string, offset *int32, promote []AnswerType, responseFilter []AnswerType, safeSearch SafeSearch, setLang string, textDecorations *bool, textFormat TextFormat) (result SearchResponse, err error) { 189 if tracing.IsEnabled() { 190 ctx = tracing.StartSpan(ctx, fqdn+"/WebClient.Search") 191 defer func() { 192 sc := -1 193 if result.Response.Response != nil { 194 sc = result.Response.Response.StatusCode 195 } 196 tracing.EndSpan(ctx, sc, err) 197 }() 198 } 199 req, err := client.SearchPreparer(ctx, query, acceptLanguage, pragma, userAgent, clientID, clientIP, location, answerCount, countryCode, count, freshness, market, offset, promote, responseFilter, safeSearch, setLang, textDecorations, textFormat) 200 if err != nil { 201 err = autorest.NewErrorWithError(err, "websearch.WebClient", "Search", nil, "Failure preparing request") 202 return 203 } 204 205 resp, err := client.SearchSender(req) 206 if err != nil { 207 result.Response = autorest.Response{Response: resp} 208 err = autorest.NewErrorWithError(err, "websearch.WebClient", "Search", resp, "Failure sending request") 209 return 210 } 211 212 result, err = client.SearchResponder(resp) 213 if err != nil { 214 err = autorest.NewErrorWithError(err, "websearch.WebClient", "Search", resp, "Failure responding to request") 215 } 216 217 return 218} 219 220// SearchPreparer prepares the Search request. 221func (client WebClient) SearchPreparer(ctx context.Context, query string, acceptLanguage string, pragma string, userAgent string, clientID string, clientIP string, location string, answerCount *int32, countryCode string, count *int32, freshness Freshness, market string, offset *int32, promote []AnswerType, responseFilter []AnswerType, safeSearch SafeSearch, setLang string, textDecorations *bool, textFormat TextFormat) (*http.Request, error) { 222 urlParameters := map[string]interface{}{ 223 "Endpoint": client.Endpoint, 224 } 225 226 queryParameters := map[string]interface{}{ 227 "q": autorest.Encode("query", query), 228 } 229 if answerCount != nil { 230 queryParameters["answerCount"] = autorest.Encode("query", *answerCount) 231 } 232 if len(countryCode) > 0 { 233 queryParameters["cc"] = autorest.Encode("query", countryCode) 234 } 235 if count != nil { 236 queryParameters["count"] = autorest.Encode("query", *count) 237 } 238 if len(string(freshness)) > 0 { 239 queryParameters["freshness"] = autorest.Encode("query", freshness) 240 } 241 if len(market) > 0 { 242 queryParameters["mkt"] = autorest.Encode("query", market) 243 } else { 244 queryParameters["mkt"] = autorest.Encode("query", "en-us") 245 } 246 if offset != nil { 247 queryParameters["offset"] = autorest.Encode("query", *offset) 248 } 249 if promote != nil && len(promote) > 0 { 250 queryParameters["promote"] = autorest.Encode("query", promote, ",") 251 } 252 if responseFilter != nil && len(responseFilter) > 0 { 253 queryParameters["responseFilter"] = autorest.Encode("query", responseFilter, ",") 254 } 255 if len(string(safeSearch)) > 0 { 256 queryParameters["safeSearch"] = autorest.Encode("query", safeSearch) 257 } 258 if len(setLang) > 0 { 259 queryParameters["setLang"] = autorest.Encode("query", setLang) 260 } 261 if textDecorations != nil { 262 queryParameters["textDecorations"] = autorest.Encode("query", *textDecorations) 263 } 264 if len(string(textFormat)) > 0 { 265 queryParameters["textFormat"] = autorest.Encode("query", textFormat) 266 } 267 268 preparer := autorest.CreatePreparer( 269 autorest.AsGet(), 270 autorest.WithCustomBaseURL("{Endpoint}/bing/v7.0", urlParameters), 271 autorest.WithPath("/search"), 272 autorest.WithQueryParameters(queryParameters), 273 autorest.WithHeader("X-BingApis-SDK", "true")) 274 if len(acceptLanguage) > 0 { 275 preparer = autorest.DecoratePreparer(preparer, 276 autorest.WithHeader("Accept-Language", autorest.String(acceptLanguage))) 277 } 278 if len(pragma) > 0 { 279 preparer = autorest.DecoratePreparer(preparer, 280 autorest.WithHeader("Pragma", autorest.String(pragma))) 281 } 282 if len(userAgent) > 0 { 283 preparer = autorest.DecoratePreparer(preparer, 284 autorest.WithHeader("User-Agent", autorest.String(userAgent))) 285 } 286 if len(clientID) > 0 { 287 preparer = autorest.DecoratePreparer(preparer, 288 autorest.WithHeader("X-MSEdge-ClientID", autorest.String(clientID))) 289 } 290 if len(clientIP) > 0 { 291 preparer = autorest.DecoratePreparer(preparer, 292 autorest.WithHeader("X-MSEdge-ClientIP", autorest.String(clientIP))) 293 } 294 if len(location) > 0 { 295 preparer = autorest.DecoratePreparer(preparer, 296 autorest.WithHeader("X-Search-Location", autorest.String(location))) 297 } 298 return preparer.Prepare((&http.Request{}).WithContext(ctx)) 299} 300 301// SearchSender sends the Search request. The method will close the 302// http.Response Body if it receives an error. 303func (client WebClient) SearchSender(req *http.Request) (*http.Response, error) { 304 sd := autorest.GetSendDecorators(req.Context(), autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...)) 305 return autorest.SendWithSender(client, req, sd...) 306} 307 308// SearchResponder handles the response to the Search request. The method always 309// closes the http.Response Body. 310func (client WebClient) SearchResponder(resp *http.Response) (result SearchResponse, err error) { 311 err = autorest.Respond( 312 resp, 313 client.ByInspecting(), 314 azure.WithErrorUnlessStatusCode(http.StatusOK), 315 autorest.ByUnmarshallingJSON(&result), 316 autorest.ByClosing()) 317 result.Response = autorest.Response{Response: resp} 318 return 319} 320