Quickstart: Perform a news search using Java and Bing News Search REST API

Use this quickstart to make your first call to Bing News Search API. This simple Java application sends a news search query to the API, and displays the JSON response.

Although this application is written in Java, the API is a RESTful Web service compatible with most programming languages.

The source code for this sample is available on GitHub.

Prerequisites

• The Java Development Kit (JDK) 7 or 8.
• The Gson library.

Create and initialize a project

1. Create a new Java project in your favorite IDE or editor, and import the following libraries:

   Java

   import java.net.*;
   import java.util.*;
   import java.io.*;
   import javax.net.ssl.HttpsURLConnection;
   import com.google.gson.Gson;
   import com.google.gson.GsonBuilder;
   import com.google.gson.JsonObject;
   import com.google.gson.JsonParser;
   

2. Create a new class. Add variables for the API endpoint, your subscription key, and search term.

   Java

   public static SearchResults SearchNews (String searchQuery) throws Exception {
       static String subscriptionKey = "enter key here";
       static String host = "https://api.bing.microsoft.com";
       static String path = "/v7.0/news/search";
       static String searchTerm = "Microsoft";
   //...
   }
   

Construct the search request, and receive a JSON response

1. Use the variables from the previous step to format a search URL for the API request. URL-encode your search term before you append it to the request.

   Java

   public static SearchResults SearchNews (String searchQuery) throws Exception {
       // construct the search request URL (in the form of URL + query string)
       URL url = new URL(host + path + "?q=" +  URLEncoder.encode(searchQuery, "UTF-8"));
       HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();
       connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);
   }
   

2. Receive the JSON response from the Bing News Search API and construct the result object.

   Java

   // receive JSON body
   InputStream stream = connection.getInputStream();
   String response = new Scanner(stream).useDelimiter("\\A").next();
   // construct result object for return
   SearchResults results = new SearchResults(new HashMap<String, String>(), response);
   

Process the JSON response

1. Separate the Bing-related HTTP headers from the JSON body, then close the stream and return the API response.

   Java

   // extract Bing-related HTTP headers
   Map<String, List<String>> headers = connection.getHeaderFields();
   for (String header : headers.keySet()) {
       if (header == null) continue;      // may have null key
       if (header.startsWith("BingAPIs-") || header.startsWith("X-MSEdge-")) {
           results.relevantHeaders.put(header, headers.get(header).get(0));
       }
   }
   stream.close();
   return results;
   

2. Create a method to parse and reserialize the JSON results.

   Java

   // pretty-printer for JSON; uses GSON parser to parse and re-serialize
   public static String prettify(String json_text) {
       JsonParser parser = new JsonParser();
       JsonObject json = parser.parse(json_text).getAsJsonObject();
       Gson gson = new GsonBuilder().setPrettyPrinting().create();
       return gson.toJson(json);
   }
   

3. In the main method of your application, call the search method and display the results.

   Java

   public static void main (String[] args) {
      System.out.println("Searching the Web for: " + searchTerm);
      SearchResults result = SearchNews(searchTerm);
   
      System.out.println("\nRelevant HTTP Headers:\n");
      for (String header : result.relevantHeaders.keySet())
            System.out.println(header + ": " + result.relevantHeaders.get(header));  
   System.out.println("\nJSON Response:\n");
   System.out.println(prettify(result.jsonResponse));
   }
   

Example JSON response

A successful response is returned in JSON, as shown in the following example:

JSON

{
   "_type": "News",
   "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/news\/search?q=Microsoft",
   "totalEstimatedMatches": 36,
   "sort": [
      {
         "name": "Best match",
         "id": "relevance",
         "isSelected": true,
         "url": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/news\/search?q=Microsoft"
      },
      {
         "name": "Most recent",
         "id": "date",
         "isSelected": false,
         "url": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/news\/search?q=Microsoft&sortby=date"
      }
   ],
   "value": [
      {
         "name": "Microsoft to open flagship London brick-and-mortar retail store",
         "url": "http:\/\/www.contoso.com\/article\/microsoft-to-open-flagshi...",
         "image": {
            "thumbnail": {
               "contentUrl": "https:\/\/www.bing.com\/th?id=ON.F9E4A49EC010417...",
               "width": 220,
               "height": 146
            }
         },
         "description": "After years of rumors about Microsoft opening a brick-and-mortar...", 
         "about": [
           {
             "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/entiti...", 
             "name": "Microsoft"
           }, 
           {
             "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/entit...", 
             "name": "London"
           }
         ], 
         "provider": [
           {
             "_type": "Organization", 
             "name": "Contoso"
           }
         ], 
          "datePublished": "2017-09-21T21:16:00.0000000Z", 
          "category": "ScienceAndTechnology"
      }, 

      . . .
      
      {
         "name": "Microsoft adds Availability Zones to its Azure cloud platform",
         "url": "https:\/\/contoso.com\/2017\/09\/21\/microsoft-adds-availability...",
         "image": {
            "thumbnail": {
               "contentUrl": "https:\/\/www.bing.com\/th?id=ON.0AE7595B9720...",
               "width": 700,
               "height": 466
            }
         },
         "description": "Microsoft has begun adding Availability Zones to its...",
         "about": [
            {
               "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/entities\/a093e9b...",
               "name": "Microsoft"
            },
            {
               "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/entities\/cf3abf7d-e379-...",
               "name": "Windows Azure"
            },
            {
               "readLink": "https:\/\/api.cognitive.microsoft.com\/api\/v7\/entities\/9cdd061c-1fae-d0...",
               "name": "Cloud"
            }
         ],
         "provider": [
            {
               "_type": "Organization",
               "name": "Contoso"
            }
         ],
         "datePublished": "2017-09-21T09:01:00.0000000Z",
         "category": "ScienceAndTechnology"
      }
   ]
}

Next steps

Create a single-page web app