Muokkaa

Jaa

Search the web for news

  • Artikkeli

Use Bing News Search API to search the Web for news that's relevant to the user's search query.

It's easy. If you have your subscription key, just send an HTTP GET request to the following endpoint:

https://api.bing.microsoft.com/v7.0/news/search

Here's a cURL example that shows you how to call the endpoint using your subscription key. Change the q query parameter to search for whatever news you'd like.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=mt+rainier

Request and response headers

Although that's all you need to do to search the Web, Bing suggests you include a couple of other headers to provide a better search experience for your user. Those headers include:

  • User-Agent — Lets Bing know whether the user needs a mobile or desktop experience.
  • X-MSEdge-ClientID — Provides continuity of experience.
  • X-MSEdge-ClientIP — Provides the user's location for location aware queries.
  • X-Search-Location — Provides the user's location for location aware queries.

The more information you can provide Bing, the better the search experience will be for your users. To learn more about these headers, see Request headers.

Here's a cURL example that includes these headers.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" -H "X-MSEdge-ClientID: 00B4230B74496E7A13CC2C1475056FF4" -H "X-MSEdge-ClientIP: 11.22.33.44" -H "X-Search-Location: lat:55;long:-111;re:22" -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.65 Safari/537.36" https://api.bing.microsoft.com/v7.0/news/search?q=mt+rainier

Bing returns a couple of headers you should capture.

  • BingAPIs-TraceId — ID that identifies the request in the log file.
  • X-MSEdge-ClientID — The ID that you need to pass in subsequent request to provide continuity of experience.
  • BingAPIs-Market — The market used by Bing for the request.

To learn more about these headers, see Response headers.

Here's a cURL call that returns the response headers. If you want to remove the response data so you can see only the headers, include the -o nul parameter.

curl -D - -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=mt+rainier

Query parameters

The only query parameter that you must pass is the q parameter, which you set to the user's query string. You must URL encode the user's query string and all query parameter values that you pass.

The API supports a number of query parameters that you can pass in your request. Here's a list of the ones you're most likely to use:

  • count and offset — Used to page image results. Read more.
  • mkt — Used to specify the market where the results come from, which is typically the market where the user is making the request from.
  • safeSearch — Used to specify the user's safe search preference.
  • textDecorations and textFormat — Used to turn on hit highlighting. Read more.

To learn more about these parameters and other parameters that you may specify, see Query parameters.

Here's a cURL example that includes these query parameters.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=mt+rainier&mkt=en-us&safeSearch=moderate&textdecorations=true&textformat=raw&count=10&offset=0

Control the freshness of the articles

If you want to limit the age of the articles are that Bing returns, check out the freshness query parameter. For example, you can request that Bing return only articles that it discovered within the last day, week, or month. The NewsArticle object's datePublished field contains the date that Bing discovered the article.

Get news from a specific site

To get news from a specific domain, add the site query operator to the user's query string.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=sailing+dinghies+site%3Acontososailing.com&mkt=en-us

Get today's top news

To get today's top news articles, simply leave the q query parameter unset.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=&mkt=en-us

The number of top news articles may vary depending on the news cycle.

Because there's a set number of top news results, the NewsAnswer object doesn't include the totalEstimatedMatches field (you cannot page top news).

The NewsAnswer also doesn't include the sort field.

Sorting the news articles

By default, the API orders the list of news articles by relevance with the most relevant articles listed first. If you want to order the articles by most recent, include the sortBy query parameter in your request and set it to date.

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=sailing&mkt=en-us&sortBy=date

The response’s sort field lists the sort options and indicates which option the request used (see the isSelected field). In the following example, the request used relevance to sort the articles.

  "sort": [
    {
      "name": "Best match",
      "id": "relevance",
      "isSelected": true,
      "url": "https://<host>/api/v7/news/search?q=sailing"
    },
    {
      "name": "Most recent",
      "id": "date",
      "isSelected": false,
      "url": "https://<host>/api/v7/news/search?q=sailing&sortby=date"
    }
  ],

Including the original image

If the article includes an image, the image is a thumbnail of the article’s original image.

      "image": {
        "thumbnail": {
          "contentUrl": "https://www.bing.com/th?id=ON.3EF9ED2DA5E74D39395D0E21...",
          "width": 700,
          "height": 525
        }
      },

To include the original image in the response, in addition to the thumbnail, include the originalImg query parameter and set it to true (the default is false).

curl -H "Ocp-Apim-Subscription-Key: <yourkeygoeshere>" https://api.bing.microsoft.com/v7.0/news/search?q=sailing&mkt=en-us&originalImg=true

Now the response includes both the contentUrl (link to the original image) and thumbnail fields.

      "image": {
        "contentUrl": "https://www.windowscentral.com/sites/wpcentral.com/files...",
        "thumbnail": {
          "contentUrl": "https://www.bing.com/th?id=ON.3EF9ED2DA5E74D39395D0E21...",
          "width": 700,
          "height": 525
        }
      },

Next steps