Quickstart: Call your Bing Custom Search endpoint using Java

  • Article

Warning

On October 30, 2020, the Bing Search APIs moved from Azure AI services to Bing Search Services. This documentation is provided for reference only. For updated documentation, see the Bing search API documentation. For instructions on creating new Azure resources for Bing search, see Create a Bing Search resource through the Azure Marketplace.

Use this quickstart to learn how to request search results from your Bing Custom Search instance. Although this application is written in Java, the Bing Custom Search API is a RESTful web service compatible with most programming languages. The source code for this sample is available on GitHub.

Prerequisites

Create an Azure resource

Start using the Bing Custom Search API by creating one of the following Azure resources.

Bing Custom Search resource

  • Available through the Azure portal until you delete the resource.
  • Use the free pricing tier to try the service, and upgrade later to a paid tier for production.

Multi-Service resource

  • Available through the Azure portal until you delete the resource.
  • Use the same key and endpoint for your applications, across multiple Azure AI services.

Create and initialize the application

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

    import java.io.InputStream;
import java.net.URL;
import java.net.URLEncoder;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Scanner;
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 class named CustomSrchJava, and then create variables for your subscription key, custom search endpoint, and search instance's custom configuration ID. You can use the global endpoint in the following code, or use the custom subdomain endpoint displayed in the Azure portal for your resource.

    public class CustomSrchJava {
    static String host = "https://api.cognitive.microsoft.com";
    static String path = "/bingcustomsearch/v7.0/search";
    static String subscriptionKey = "YOUR-SUBSCRIPTION-KEY"; 
    static String customConfigId = "YOUR-CUSTOM-CONFIG-ID";
    static String searchTerm = "Microsoft";  
...

  3. Create another class named SearchResults to contain the response from your Bing Custom Search instance.

    class SearchResults {
    HashMap<String, String> relevantHeaders;
    String jsonResponse;
    SearchResults(HashMap<String, String> headers, String json) {
        relevantHeaders = headers;
        jsonResponse = json;
    }
}

  4. Create a function named prettify() to format the JSON response from the Bing Custom Search API.

        // 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);
    }

Send and receive a search request

  1. Create a function named SearchWeb() that sends a request and returns a SearchResults object. Create the request url by combining your custom configuration ID, query, and endpoint information. Add your subscription key to the Ocp-Apim-Subscription-Key header.

    public class CustomSrchJava {
...
    public static SearchResults SearchWeb (String searchQuery) throws Exception {
        // construct the URL for your search request (endpoint + query string)
        URL url = new URL(host + path + "?q=" +  URLEncoder.encode(searchTerm, "UTF-8") + "&CustomConfig=" + customConfigId);
        HttpsURLConnection connection = (HttpsURLConnection)url.openConnection();
        connection.setRequestProperty("Ocp-Apim-Subscription-Key", subscriptionKey);
...

  2. Create a stream and store the JSON response in a SearchResults object.

    public class CustomSrchJava {
...
    public static SearchResults SearchWeb (String searchQuery) throws Exception {
        ...
        // receive the 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);

        stream.close();
        return results;
    }

  3. Print the JSON response.

    System.out.println("\nJSON Response:\n");
System.out.println(prettify(result.jsonResponse));

  4. Run the program.

Next steps

Build a Custom Search web app