Bing News Search とはWhat is Bing News Search?

Bing News Search API は、Bing News に似た (ただし、厳密に同じではありません) エクスペリエンスを提供します。The Bing News Search API provides a similar (but not exact) experience to Bing News. Bing News Search API を使うと、検索クエリを Bing に送信し、関連するニュース記事の一覧を取得できます。The Bing News Search API lets you send a search query to Bing and get back a list of relevant news articles.

ユーザーの検索クエリと関連性の高いニュースを探し出すことを目的として、ニュースのみの検索結果ページを作成する場合は、より汎用性の高い Bing Web Search API ではなく、こちらの API を呼び出してください。If you're building a news-only search results page to find news that's relevant to the user's search query, call this API instead of calling the more general Bing Web Search API. ニュースだけでなく、Web ページや画像、動画など、他の種類のコンテンツも対象にする場合は、Bing Web Search API を呼び出します。If you want news and other types of content such as webpages, images, and videos, then call the Bing Web Search API.

検索語句の補完と使用Suggesting & using search terms

ユーザーが検索語句を入力するための検索ボックスを用意する場合は、Bing Autosuggest API を使用することでエクスペリエンスが向上します。If you provide a search box where the user enters their search term, use the Bing Autosuggest API to improve the experience. この API は、検索語句をユーザーが入力している最中に、その一部分に基づいてクエリ文字列の候補を返します。The API returns suggested query strings based on partial search terms as the user types.

ユーザーが検索語句を入力した後、それを URL エンコードしたうえで、q クエリ パラメーターを設定します。After the user enters their search term, URL encode it before setting the q query parameter. たとえば「sailing dinghies」と入力された場合、qsailing+dinghies または sailing%20dinghies に設定します。For example, if the user enters sailing dinghies, set q to sailing+dinghies or sailing%20dinghies.

通常のニュースの取得Getting general news

ユーザーの検索語句に関連した通常のニュース記事を Web から取得するには、次の GET 要求を送信します。To get general news articles related to the user's search term from the web, send the following GET request:

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=sailing+dinghies&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

いずれかの Bing API を初めて呼び出す場合は、クライアント ID ヘッダーを含めないでください。If it's your first time calling any of the Bing APIs, don't include the client ID header. クライアント ID を含めるのは、過去に Bing API を呼び出したことがあり、かつユーザーとデバイスの組み合わせに対応するクライアント ID が Bing から返されたことがある場合だけです。Only include the client ID if you've previously called a Bing API and Bing returned a client ID for the user and device combination.

特定のドメインからニュースを取得するには、site: というクエリ演算子を使用します。To get news from a specific domain, use the site: query operator.

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=sailing+dinghies+site:contososailing.com&mkt=en-us HTTP/1.1

前のクエリに対する応答を次に示します。The following shows the response to the previous query. それらの各ニュース記事は、応答に含まれている順序で表示する必要があります。You must display each news article in the order provided in the response. 記事にクラスター化されている記事が含まれる場合、関連する記事が存在することを示し、ユーザーが要求した場合にそれらを表示する必要があります。If the article has clustered articles, you should indicate that related articles exist and display them if the user requests to see them.

{
    "_type" : "News",
    "readLink" : "https:\/\/api.cognitive.microsoft.com\/bing\/v5\/news\/search?q=sailing+dinghies",
    "totalEstimatedMatches" : 88400,
    "value" : [{
        "name" : "Sailing Vies for Four Trophies",
        "url" : "http:\/\/www.bing.com\/cr?IG=CCE2F06CA750455891FE99A72...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.9C23AA5...",
                "width" : 650,
                "height" : 341
            }
        },
        "description" : "College Rankings, presented by Zim...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "contoso.com"
        }],
        "datePublished" : "2017-04-14T15:28:00"
    },

    ...

    {
        "name" : "Fabrikam Sailing Club to host Mirror Dinghy...",
        "url" : "http:\/\/www.bing.com\/cr?IG=CCE2F06CA750455891F...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.36...",
                "width" : 448,
                "height" : 300
            }
        },
        "description" : "The sailing club that trained Olympian Ben...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "Contoso"
        }],
        "datePublished" : "2017-04-04T11:02:00",
        "category" : "Sports"
    }]
}

news 回答には、そのクエリとの関連性が高いと Bing によって判断された一連のニュース記事が格納されます。The news answer lists the news articles that Bing thought were relevant to the query. 表示できる記事の数の見積もりは、totalEstimatedMatches フィールドに格納されます。The totalEstimatedMatches field contains an estimate of the number of articles available to view. 記事のページングの詳細については、「ニュースのページング」を参照してください。For information about paging through the articles, see Paging News.

このリスト内の各 newsarticle には、その記事の名前や説明、さらに、ホストの Web サイト上の記事への URL が含まれています。Each news article in the list includes the article's name, description, and URL to the article on the host's website. 記事に画像が含まれている場合、このオブジェクトには、その画像のサムネイルが含まれます。If the article contains an image, the object includes a thumbnail of the image. ホストのサイト上にあるニュース記事にユーザーを誘導するハイパーリンクを作成するには、nameurl を使用します。Use name and url to create a hyperlink that takes the user to the news article on the host's site. 記事に画像が含まれる場合は、url を使用して画像もクリックできるようにします。If the article includes an image, also make the image clickable using url. 必ず provider を使用して記事の帰属を示すようにしてください。Be sure to use provider to attribute the article.

Bing がニュース記事のカテゴリを決定できる場合、記事に category フィールドが含まれます。If Bing can determine the category of news article, the article includes the category field.

今日のトップ ニュースを取得するGetting today's top news

今日のトップ ニュース記事を取得するには、q を設定しない点を除き、通常のニュースを取得するのと同じ要求を行います。To get today's top news articles, you'd make the same request as getting general news except that you'd leave q unset.

GET https://api.cognitive.microsoft.com/bing/v7.0/news/search?q=&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

トップ ニュースを取得する際の応答は、通常のニュースを取得する場合とほとんど同じです。The response for getting top news is almost the same as getting general news. ただし、結果の数は決まっているので、news 応答に totalEstimatedMatches フィールドは含まれません。However, the news answer doesn't include the totalEstimatedMatches field because there's a set number of results. トップ ニュース記事の数は、ニュース サイクルによって異なる場合があります。The number of top news articles may vary depending on the news cycle. 必ず provider を使用して記事の帰属を示すようにしてください。Be sure to use provider to attribute the article.

カテゴリ別のニュースを取得するGetting news by category

トップ スポーツ、エンターテイメント記事など、カテゴリ別にニュース記事を取得するには、Bing に次の GET 要求を送信します。To get news articles by category, such as the top sports or entertainment articles, send the following GET request to Bing:

GET https://api.cognitive.microsoft.com/bing/v7.0/news?category=sports&mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

category クエリ パラメーターを使用して、取得する記事のカテゴリを指定します。Use the category query parameter to specify the category of articles to get. 指定可能なニュース カテゴリの一覧は、「News Categories by Market (マーケット別ニュース カテゴリ)」を参照してください。For a list of possible news categories that you may specify, see News Categories by Market.

カテゴリ別にニュースを取得する際の応答は、通常のニュースの取得とほとんど同じです。The response for getting news by category is almost the same as getting general news. ただし、記事はすべて指定したカテゴリのものです。However, the articles are all from the specified category.

ヘッドライン ニュースを取得するGetting headline news

ヘッドライン ニュース記事を要求してすべてのニュース カテゴリから記事を取得するには、Bing に次の GET 要求を送信します。To request headline news articles and get articles from all news categories, send the following GET request to Bing:

GET https://api.cognitive.microsoft.com/bing/v7.0/news?mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-MSEdge-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

category クエリ パラメーターは含めないでください。Do not include the category query parameter.

ヘッドライン ニュースを取得する際の応答は、今日のトップ ニュースを取得する場合と同じです。The response for getting headline news is the same as getting today's top news. 記事がヘッドライン記事である場合、headline フィールドが true に設定されます。If the article is a headline article, its headline field is set to true.

既定では、応答には最大 12 個のヘッドライン記事が含まれます。By default, the response includes up to 12 headline articles. 返されるヘッドライン記事の数を変更するには、headlineCount クエリ パラメーターを指定します。To change the number of headline articles to return, specify the headlineCount query parameter. 応答には、ニュースのカテゴリ 1 つにつき最大 4 つの非ヘッドライン記事も含まれます。The response also includes up to four non-headline articles per news category.

応答では、クラスターは 1 つの記事としてカウントされます。The response counts clusters as one article. クラスターには複数の記事が含まれる可能性があるため、12 を超えるヘッドライン記事や、1 つのカテゴリにつき 4 つを超える非ヘッドライン記事が応答に含まれる場合があります。Because a cluster may have several articles, the response may include more than 12 headline articles and more than four non-headline articles per category.

ソーシャル ネットワークでトレンドになっているニュース トピックを取得するには、Bing に次の GET 要求を送信します。To get news topics that are trending on social networks, send the following GET request to Bing:

GET https://api.cognitive.microsoft.com/bing/v7.0/news/trendingtopics?mkt=en-us HTTP/1.1
Ocp-Apim-Subscription-Key: 123456789ABCDE
User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows Phone 8.0; Trident/6.0; IEMobile/10.0; ARM; Touch; NOKIA; Lumia 822)
X-Search-ClientIP: 999.999.999.999
X-Search-Location: lat:47.60357;long:-122.3295;re:100
X-MSEdge-ClientID: <blobFromPriorResponseGoesHere>
X-MSAPI-UserState: <blobFromPriorResponseGoesHere>
Host: api.cognitive.microsoft.com

注意

トレンドのトピックは、en-US および zh-CN マーケットでのみ使用できます。Trending Topics is available only in the en-US and zh-CN markets.

前述の要求への応答は次の JSON のようになります。The following JSON is the response to the preceding request. 各トレンドのニュース記事には、関連する画像、ニュース速報フラグ、および記事の Bing 検索結果の URL が含まれています。Each trending news article includes a related image, breaking news flag, and a URL to the Bing search results for the article. webSearchUrl フィールドの URL を使用して、ユーザーを Bing 検索結果ページに誘導します。Use the URL in the webSearchUrl field to take the user to the Bing search results page. または、クエリ テキストを使用して Web Search API を呼び出し、自分で結果を表示します。Or, use the query text to call the Web Search API to display the results yourself.

{
    "_type" : "TrendingTopics",
    "value" : [{
        "name" : "Canada pot measure",
        "image" : {
            "url" : "https:\/\/www.bing.com\/th?id=OPN.RTNews_hHD...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso Images"
            }]
        },
        "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=070292D8CEDD...",
        "isBreakingNews" : false,
        "query" : {
            "text" : "Canada marijuana"
        }
    },
    {
        "name" : "Down on Vegas move",
        "image" : {
            "url" : "https:\/\/www.bing.com\/th?id=OPN.RTNews_Bfbmg8h...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso"
            }]
        },
        "webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=070292D8CEDD...",
        "isBreakingNews" : false,
        "query" : {
            "text" : "Marcus Appel Las Vegas"
        }
    },

    ...

    ]
}

ニュース記事に関連する他の記事がある場合、ニュース記事に clusteredArticles フィールドが含まれる場合があります。If there are other articles that are related to a news article, the news article may include the clusteredArticles field. 次に、クラスター化された記事を含む記事を示します。The following shows an article with clustered articles.

    {
        "name" : "Playoffs 2017: Betting lines, point spreads...",
        "url" : "http:\/\/www.bing.com\/cr?IG=4B7056CEC271408997D115...",
        "image" : {
            "thumbnail" : {
                "contentUrl" : "https:\/\/www.bing.com\/th?id=ON.D7B1...",
                "width" : 700,
                "height" : 393
            }
        },
        "description" : "April 14, 2017 3:37pm EDT April 14, 2017 3:34pm...",
        "provider" : [{
            "_type" : "Organization",
            "name" : "Contoso"
        }],
        "datePublished" : "2017-04-14T19:43:00",
        "category" : "Sports",
        "clusteredArticles" : [{
            "name" : "Playoffs 2017: Betting odds, favorites to win...",
            "url" : "http:\/\/www.bing.com\/cr?IG=4B7056CEC271408997D1159E...",
            "description" : "April 14, 2017 3:30pm EDT April 14, 2017 3:27pm...",
            "provider" : [{
                "_type" : "Organization",
                "name" : "Contoso"
            }],
            "datePublished" : "2017-04-14T19:37:00",
            "category" : "Sports"
        }]
    },

スロットル リクエストThrottling requests

サービスとサブスクリプションの種類によって、1 秒あたりのクエリ数 (QPS) が決まります。The service and your subscription type determine the number of queries per second (QPS) that you can make. アプリケーションに、クォータ内に収めるロジックを含めるようにしてください。Make sure your application includes the logic to stay within your quota. QPS の上限に達するか超えた場合、要求は失敗し、HTTP 429 状態コードが返されます。If the QPS limit is met or exceeded, the request fails and an HTTP 429 status code is returned. 応答には、Retry-After ヘッダーが含まれています。これは、別の要求を送信できるようになるまでに待機する必要がある時間を示します。The response includes the Retry-After header, which indicates how long you must wait before sending another request.

サービス拒否とスロットリングDenial-of-service versus throttling

このサービスは、サービス拒否 (DoS) 攻撃と QPS 違反を区別しています。The service makes a differentiation between a denial-of-service (DoS) attack and a QPS violation. サービスが DoS 攻撃を疑っている場合、要求は成功します (HTTP 状態コードは 200 OK)。If the service suspects a DoS attack, the request succeeds (HTTP status code is 200 OK). しかし、応答の本文は空になります。However, the body of the response is empty.

次の手順Next steps

実際に要求を送信してみるには、最初の要求を行うに関するページを参照してください。To get started quickly with your first request, see Making Your First Request.

Bing News Search API v7 リファレンスを活用してください。Familiarize yourself with the Bing News Search API v7 reference. リファレンスには、検索結果を要求する際に使用するエンドポイント、ヘッダー、クエリ パラメーターの一覧が記載されています。The reference contains the list of endpoints, headers, and query parameters that you'd use to request search results. また、応答オブジェクトの定義も記載されています。It also includes definitions of the response objects.

検索ボックスのユーザー エクスペリエンスを高めるには、Bing Autosuggest API に関するページを参照してください。To improve your search box user experience, see Bing Autosuggest API. ユーザーによって検索語が入力されている最中に、この API を呼び出すことで、他のユーザーによって使用された関連性の高い検索語を取得できます。As the user enters their query term, you can call this API to get relevant query terms that were used by others.

検索結果の使用に関するルールを逸脱しないよう、Bing の使用上および表示上の要件に関するページを必ず読んでください。Be sure to read Bing Use and Display Requirements so you don't break any of the rules about using the search results.