Quickstart: Use the Bing Custom Search client library
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.
Get started with the Bing Custom Search client library for C#. Follow these steps to install the package and try out the example code for basic tasks. The Bing Custom Search API enables you to create tailored, ad-free search experiences for topics that you care about. The source code for this sample can be found on GitHub.
Use the Bing Custom Search client library for C# to:
- Find search results on the web, from your Bing Custom Search instance.
Reference documentation | Library source code | Package (NuGet) | Samples
Prerequisites
- A Bing Custom Search instance. See Quickstart: Create your first Bing Custom Search instance for more information.
- Microsoft .NET Core
- Any edition of Visual Studio 2017 or later
- If you are using Linux/MacOS, this application can be run using Mono.
- The Bing Custom Search NuGet package.
- From Solution Explorer in Visual Studio, right-click your project and select Manage NuGet Packages from the menu. Install the
Microsoft.Azure.CognitiveServices.Search.CustomSearch
package. Installing the NuGet Custom Search package also installs the following assemblies:- Microsoft.Rest.ClientRuntime
- Microsoft.Rest.ClientRuntime.Azure
- Newtonsoft.Json
- From Solution Explorer in Visual Studio, right-click your project and select Manage NuGet Packages from the menu. Install the
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
Create a new C# console application in Visual Studio. Then add the following packages to your project.
using System; using System.Linq; using Microsoft.Azure.CognitiveServices.Search.CustomSearch;
In the main method of your application, instantiate the search client with your API key.
var client = new CustomSearchAPI(new ApiKeyServiceClientCredentials("YOUR-SUBSCRIPTION-KEY"));
Send the search request and receive a response
Send a search query using your client's
SearchAsync()
method, and save the response. Be sure to replace yourYOUR-CUSTOM-CONFIG-ID
with your instance's configuration ID (you can find the ID in the Bing Custom Search portal). This example searches for "Xbox".// This will look up a single query (Xbox). var webData = client.CustomInstance.SearchAsync(query: "Xbox", customConfig: Int32.Parse("YOUR-CUSTOM-CONFIG-ID")).Result;
The
SearchAsync()
method returns aWebData
object. Use the object to iterate through anyWebPages
that were found. This code finds the first webpage result and prints the webpage'sName
andURL
.if (webData?.WebPages?.Value?.Count > 0) { // find the first web page var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault(); if (firstWebPagesResult != null) { Console.WriteLine("Number of webpage results {0}", webData.WebPages.Value.Count); Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name); Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url); } else { Console.WriteLine("Couldn't find web results!"); } } else { Console.WriteLine("Didn't see any Web data.."); }
Next steps
Get started with the Bing Custom Search client library for Java. Follow these steps to install the package and try out the example code for basic tasks. The Bing Custom Search API enables you to create tailored, ad-free search experiences for topics that you care about. The source code for this sample can be found on GitHub
Use the Bing Custom Search client library for Java to:
- Find search results on the web, from your Bing Custom Search instance.
Reference documentation | Library source code | Artifact (Maven) | Samples
Prerequisites
- Azure subscription - Create one for free.
- The current version of the Java Development Kit (JDK).
- The Gradle build tool, or another dependency manager.
- A Bing Custom Search instance. See Quickstart: Create your first Bing Custom Search instance for more information.
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.
After you get a key from your resource, create an environment variable for the key, named AZURE_BING_CUSTOM_SEARCH_API_KEY
.
Create a new Gradle project
Tip
If you're not using Gradle, you can find the client library details for other dependency managers on the Maven Central Repository.
In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.
mkdir myapp && cd myapp
Run the gradle init
command from your working directory. This command creates essential build files for Gradle, including a build.gradle.kts file that is used at runtime to configure your application.
gradle init --type basic
When prompted to choose a DSL, select Kotlin.
Install the client library
Locate build.gradle.kts and open it with your preferred IDE or text editor. Then copy in this build configuration. Be sure to include the client library under dependencies
:
plugins {
java
application
}
application {
mainClassName = "main.java.BingCustomSearchSample"
}
repositories {
mavenCentral()
}
dependencies {
compile("org.slf4j:slf4j-simple:1.7.25")
compile("com.microsoft.azure.cognitiveservices:azure-cognitiveservices-customsearch:1.0.2")
}
Create a folder for your sample app. From your working directory, run the following command:
mkdir src/main/java
Navigate to the new folder and create a file called BingCustomSearchSample.java. Open it and add the following import
statements:
package main.java;
import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchAPI;
import com.microsoft.azure.cognitiveservices.search.customsearch.BingCustomSearchManager;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.SearchResponse;
import com.microsoft.azure.cognitiveservices.search.customsearch.models.WebPage;
Create a class named BingCustomSearchSample
public class BingCustomSearchSample {
}
In the class, create a main
method and a variable for your resource's key. If you created the environment variable after you launched the application, close and reopen the editor, IDE, or shell running it to access the variable. You will define the methods later.
public static void main(String[] args) {
try {
// Set the BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY and AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID environment variables,
// then reopen your command prompt or IDE. If not, you may get an API key not found exception.
final String subscriptionKey = System.getenv("BING_CUSTOM_SEARCH_SUBSCRIPTION_KEY");
// If you do not have a customConfigId, you can also use 1 as your value when setting your environment variable.
final String customConfigId = System.getenv("AZURE_BING_SAMPLES_CUSTOM_CONFIG_ID");
BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);
runSample(client, customConfigId);
} catch (Exception e) {
System.out.println(e.getMessage());
e.printStackTrace();
}
}
Object model
The Bing Custom Search client is a BingCustomSearchAPI object that's created from the BingCustomSearchManager object's authenticate() method. You can send a search request using the client's BingCustomInstances.search() method.
The API response is a SearchResponse object containing information on the search query, and search results.
Code examples
These code snippets show you how to do the following tasks with the Bing Custom Search client library for Java:
Authenticate the client
Your main method should include a BingCustomSearchManager object that takes your key, and calls its authenticate()
.
BingCustomSearchAPI client = BingCustomSearchManager.authenticate(subscriptionKey);
Get search results from your custom search instance
Use the client's BingCustomInstances.search() function to send a search query to your custom instance. Set the withCustomConfig
to your custom configuration ID, or default to 1
. After getting a response from the API, check if any search results were found. If so, get the first search result by calling the response's webPages().value().get()
function and print the result's name, and URL.
public static boolean runSample(BingCustomSearchAPI client, String customConfigId) {
try {
// This will search for "Xbox" using Bing Custom Search
//and print out name and url for the first web page in the results list
System.out.println("Searching for Query: \"Xbox\"");
SearchResponse webData = client.bingCustomInstances().search()
.withCustomConfig(customConfigId != null ? Long.valueOf(customConfigId) : 0)
.withQuery("Xbox")
.withMarket("en-us")
.execute();
if (webData != null && webData.webPages() != null && webData.webPages().value().size() > 0)
{
// find the first web page
WebPage firstWebPagesResult = webData.webPages().value().get(0);
if (firstWebPagesResult != null) {
System.out.println(String.format("Webpage Results#%d", webData.webPages().value().size()));
System.out.println(String.format("First web page name: %s ", firstWebPagesResult.name()));
System.out.println(String.format("First web page URL: %s ", firstWebPagesResult.url()));
} else {
System.out.println("Couldn't find web results!");
}
} else {
System.out.println("Didn't see any Web data..");
}
return true;
} catch (Exception f) {
System.out.println(f.getMessage());
f.printStackTrace();
}
return false;
}
Run the application
Build the app with the following command from your project's main directory:
gradle build
Run the application with the run
goal:
gradle run
Clean up resources
If you want to clean up and remove an Azure AI services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with it.
Next steps
Get started with the Bing Custom Search client library for Python. Follow these steps to install the package and try out the example code for basic tasks. The Bing Custom Search API enables you to create tailored, ad-free search experiences for topics that you care about.The source code for this sample can be found on GitHub.
Use the Bing Custom Search client library for Python to:
- Find search results on the web, from your Bing Custom Search instance.
Reference documentation | Library source code | Package (PyPi) | Samples
Prerequisites
- A Bing Custom Search instance. See Quickstart: Create your first Bing Custom Search instance for more information.
- Python 2.x or 3.x
- The Bing Custom Search SDK for Python
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.
Install the Python client library
Install the Bing Custom Search client library with the following command.
python -m pip install azure-cognitiveservices-search-customsearch
Create a new application
Create a new Python file in your favorite editor or IDE, and add the following imports.
from azure.cognitiveservices.search.customsearch import CustomSearchClient
from msrest.authentication import CognitiveServicesCredentials
Create a search client and send a request
Create a variable for your subscription key and endpoint.
subscription_key = 'your-subscription-key' endpoint = 'your-endpoint'
Create an instance of
CustomSearchClient
, using aCognitiveServicesCredentials
object with the subscription key.client = CustomSearchClient(endpoint=endpoint, credentials=CognitiveServicesCredentials(subscription_key))
Send a search request with
client.custom_instance.search()
. Append your search term to thequery
parameter, and setcustom_config
to your Custom Configuration ID to use your search instance. You can get your ID from the Bing Custom Search portal, by clicking the Production tab.web_data = client.custom_instance.search(query="xbox", custom_config="your-configuration-id")
View the search results
If any web page search results were found, get the first one and print its name, URL, and total web pages found.
if web_data.web_pages.value:
first_web_result = web_data.web_pages.value[0]
print("Web Pages result count: {}".format(len(web_data.web_pages.value)))
print("First Web Page name: {}".format(first_web_result.name))
print("First Web Page url: {}".format(first_web_result.url))
else:
print("Didn't see any web data..")