Bing Webmaster API

https://learn.microsoft.com/en-us/bingwebmaster
Admin
Bing Webmaster API enables webmasters to programmatically access website information on Bing search,...
Tokens:5,858
Snippets:56
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Retrieve Traffic and Rank Stats

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

C# example to fetch and display traffic and rank statistics for the past month using the Webmaster API.

```csharp
namespace WebmasterApiExamples
{
    using System;
    using System.Linq;
    using System.ServiceModel;

    internal class Program
    {
        private static void Main(string[] args)
        {
            var api = new WebmasterApi.WebmasterApiClient();

            try
            {
                var oneMonthAgo = DateTime.Now.AddMonths(-1);
                var stats = api.GetRankAndTrafficStats("http://yoursite.com/")
                    .Where(s => s.Date > oneMonthAgo)
                    .OrderBy(s => s.Date);
                Console.WriteLine("Date\tImpressions\tClicks");
                foreach (var value in stats)
                {
                    Console.WriteLine("{0}\t{1}\t{2}", value.Date.ToShortDateString(), value.Impressions, value.Clicks);
                }
            }
            catch (FaultException<WebmasterApi.ApiFault> fault)
            {
                Console.WriteLine("Failed to add site: {0}", fault.Message);
            }
        }
    }
}

```

--------------------------------

### POX Error Response Sample

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

Example of an HTTP 400 error response for POX protocol, indicating an invalid API key.

```http
HTTP/1.1 400 Error
Content-Length: 97
Content-Type: application/xml; charset=utf-8

<root type="object"><ErrorCode type="number">3</ErrorCode><Message>InvalidApiKey</Message></root>

```

--------------------------------

### Constructing an OAuth 2.0 Authorization URL

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

This example shows how to build the URL to redirect users to Bing Webmaster for OAuth 2.0 authorization. Ensure you replace placeholders with your actual client ID, redirect URI, and desired scope.

```plaintext
https://www.bing.com/webmasters/oauth/authorize?response_type=code& 
client_id=449986cfb7504861996ba2f443210776& 
redirect_uri=https%3A%2F%2Fexample.com%2Fcallback& 
scope=webmaster.manage

```

--------------------------------

### GetRankAndTrafficStats

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

Retrieves traffic and ranking statistics for a given site URL over a specified period. This example shows how to fetch data for the last month and display impressions and clicks.

```APIDOC
## GetRankAndTrafficStats

### Description
Retrieves traffic and ranking statistics for a given site URL. The example demonstrates fetching data for the last month and displaying impressions and clicks.

### Method
SOAP (via C# client)

### Endpoint
`https://ssl.bing.com/webmaster/api.svc/soap?apikey=API_KEY`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **apikey** (string) - Required - Your Webmaster API Key.

#### Request Body
This method is called via a SOAP client, so there is no direct request body in the HTTP sense. The parameters are passed as arguments to the client method.
- **url** (string) - Required - The URL of the site verified in Bing Webmaster Tools.

### Request Example
```csharp
var api = new WebmasterApi.WebmasterApiClient();
var oneMonthAgo = DateTime.Now.AddMonths(-1);
var stats = api.GetRankAndTrafficStats("http://yoursite.com/")
    .Where(s => s.Date > oneMonthAgo)
    .OrderBy(s => s.Date);
```

### Response
#### Success Response
Returns a collection of statistics objects, each containing Date, Impressions, and Clicks.

#### Response Example
```
Date	Impressions	Clicks
10/13/2022	1000	50
10/14/2022	1100	55
```

### Error Handling
- **SOAP Protocol**: `FaultException<WebmasterApi.ApiFault>`
- **POX/JSON Protocols**: HTTP status code 400 with an error description in the body.

**POX error response sample**
```
HTTP/1.1 400 Error
Content-Length: 97
Content-Type: application/xml; charset=utf-8

<root type="object"><ErrorCode type="number">3</ErrorCode><Message>InvalidApiKey</Message></root>
```

**JSON error response sample**
```
HTTP/1.1 400 Error
Content-Length: 41
Content-Type: application/json; charset=utf-8

{"ErrorCode":3,"Message":"InvalidApiKey"}
```
```

--------------------------------

### JSON Error Response Sample

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

Example of an HTTP 400 error response for JSON protocol, indicating an invalid API key.

```json
HTTP/1.1 400 Error
Content-Length: 41
Content-Type: application/json; charset=utf-8

{"ErrorCode":3,"Message":"InvalidApiKey"}

```

--------------------------------

### POX/HTTP Protocol URL Format

Source: https://learn.microsoft.com/en-us/bingwebmaster/api-protocols

This snippet shows the URL formats for making requests to the Bing Webmaster Tools API using the POX/HTTP protocol. It includes formats for both GET and POST requests.

```APIDOC
## POX/HTTP Protocol URL Format

### Description
Provides the URL structure for interacting with the Bing Webmaster Tools API via POX/HTTP.

### Protocol Formats

#### POX GET
`https://ssl.bing.com/webmaster/api.svc/pox/METHOD_NAME?apikey=API_KEY&param1=VALUE&param2=VALUE&...&paramN=VALUE`

#### POX POST
`https://ssl.bing.com/webmaster/api.svc/pox/METHOD_NAME?apikey=API_KEY`
```

--------------------------------

### Access Bing Webmaster API using Access Token

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Include the obtained access token in the Authorization HTTP header as a Bearer token to make authenticated calls to Bing Webmaster APIs. This example shows a request to the SubmitUrl API.

```HTTP
POST /webmaster/api.svc/json/SubmitUrl HTTP/1.1 
Host: www.bing.com 
Content-Type: application/json 

Authorization: Bearer 2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ 
{
    "siteUrl":"https://www.example.com",
    "url":"https://www.example.com/url1"
}

```

--------------------------------

### JSON/HTTP Protocol URL Format

Source: https://learn.microsoft.com/en-us/bingwebmaster/api-protocols

This snippet outlines the URL formats for making requests to the Bing Webmaster Tools API using the JSON/HTTP protocol. It includes formats for both GET and POST requests.

```APIDOC
## JSON/HTTP Protocol URL Format

### Description
Provides the URL structure for interacting with the Bing Webmaster Tools API via JSON/HTTP.

### Protocol Formats

#### JSON GET
`https://ssl.bing.com/webmaster/api.svc/json/METHOD_NAME?apikey=API_KEY&param1=VALUE&param2=VALUE&...&paramN=VALUE`

#### JSON POST
`https://ssl.bing.com/webmaster/api.svc/json/METHOD_NAME?apikey=API_KEY`
```

--------------------------------

### Sample Response for New Access Token

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

This JSON object is returned by the token server upon a successful request for a new access token. It contains the new access token, its expiration time, and token type.

```json
{
    "access_token": "eyJ3ZWJtYXN0ZXJl…2VibWFzdGVydWlkIjoiMDY3MDY",
    "expires_in": 3599,
    "token_type": "Bearer"
}

```

--------------------------------

### SOAP Endpoint Configuration

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

XML configuration for a SOAP endpoint in app.config, specifying the API key and binding.

```xml
<endpoint address="https://ssl.bing.com/webmaster/api.svc/soap?apikey=EEDECC1EA4AE341CC57365E075EBC8B6" binding="basicHttpBinding" bindingConfiguration="BasicHttpBinding_IWebmasterApi" contract="WebmasterApi.IWebmasterApi" name="BasicHttpBinding_IWebmasterApi" />

```

--------------------------------

### Handling OAuth 2.0 Authorization Denied Response

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

This is a sample URL demonstrating how your application would receive an 'access_denied' error from the Bing Webmaster OAuth 2.0 server. This occurs when the user does not approve the access request.

```plaintext
https://example.com/callback/auth?error=access_denied
```

--------------------------------

### SOAP API Fault Exception Handling

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

C# code snippet demonstrating how to catch a SOAP protocol error using FaultException.

```csharp
catch (FaultException<WebmasterApi.ApiFault> fault)
{
    // handle error
}

```

--------------------------------

### Request Access and Refresh Tokens

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Exchange an authorization code for an access token and a refresh token by making a POST request to the /token endpoint. The authorization code is valid for 5 minutes.

```APIDOC
## POST /webmasters/oauth/token

### Description
Exchanges an authorization code for an access token and a refresh token.

### Method
POST

### Endpoint
https://www.bing.com/webmasters/oauth/token

### Parameters
#### Request Body
Parameters must be encoded in `application/x-www-form-urlencoded`.

- **client_id** (string) - Required - The client ID for your application.
- **client_secret** (string) - Required - The client secret for your application.
- **code** (string) - Required - The authorization code received from the initial request.
- **grant_type** (string) - Required - This field must contain the value: `authorization_code`.
- **redirect_uri** (string) - Required - The URI to redirect to after the user grants or denies permission.

### Request Example
```
POST /webmasters/oauth/token HTTP/1.1
Host: www.bing.com 
Content-Type: application/x-www-form-urlencoded

code= L4yRDynJso8B9RqYT-a0B1Oct-FNxPzZWd9FfU07QWA&
client_id= 449986cfb7504861996ba2f443210776 &
client_secret= SP313W-3hpgWXaq_S6P-J2-d1_xsLc4Fs…XOzHGQioA&
redirect_uri= https%3A%2F%2Fexample.com%2Fcallback &
grant_type= authorization_code
```

### Response
#### Success Response (200 OK)
Returns a JSON object containing the access token, refresh token, and their validity periods.

- **access_token** (string) - The token required to authorize Bing Webmaster API requests.
- **expires_in** (integer) - The time period (in seconds) for which the access token is valid.
- **refresh_token** (string) - A token used to obtain a new access token.
- **token_type** (string) - The type of token returned. Always `Bearer`.

#### Response Example
```json
{
    "access_token": "2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ",
    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "eyJ0eXI7vgiEjC…zqoTD-MRJ9D8J06vp_39oWiA"
}
```
```

--------------------------------

### Request New Access Token

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Obtain a new access token by sending a POST request to the token endpoint with your client credentials and refresh token.

```APIDOC
## POST /webmasters/token

### Description
Requests a new access token using a valid refresh token. Access tokens have a limited lifetime and expire.

### Method
POST

### Endpoint
https://www.bing.com/webmasters/token

### Parameters
#### Request Body
- **client_id** (string) - Required - The client ID for your application.
- **client_secret** (string) - Required - The client secret for your application.
- **grant_type** (string) - Required - This field must contain the value: `refresh_token`.
- **refresh_token** (string) - Required - The refresh token returned from the authorization code exchange.

### Request Example
```json
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "grant_type": "refresh_token"
}
```

### Response
#### Success Response (200)
- **access_token** (string) - The new access token.
- **expires_in** (integer) - The lifetime in seconds of the access token.
- **token_type** (string) - The type of token, typically "Bearer".

#### Response Example
```json
{
    "access_token": "eyJ3ZWJtYXN0ZXJl…2VibWFzdGVydWlkIjoiMDY3MDY",
    "expires_in": 3599,
    "token_type": "Bearer"
}
```
```

--------------------------------

### Request Access Token with Authorization Code

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Exchange an authorization code for an access token and refresh token by making a POST request to the /token endpoint. The authorization code is valid for 5 minutes.

```HTTP
POST /webmasters/oauth/token HTTP/1.1
Host: www.bing.com 
Content-Type: application/x-www-form-urlencoded

code= L4yRDynJso8B9RqYT-a0B1Oct-FNxPzZWd9FfU07QWA&
client_id= 449986cfb7504861996ba2f443210776 &
client_secret= SP313W-3hpgWXaq_S6P-J2-d1_xsLc4Fs…XOzHGQioA&
redirect_uri= https%3A%2F%2Fexample.com%2Fcallback &
grant_type= authorization_code

```

--------------------------------

### Handling OAuth 2.0 Authorization Code Response

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

This is a sample URL showing a successful response from the Bing Webmaster OAuth 2.0 server, containing an authorization code. Your application will receive this code at the specified redirect URI after user approval.

```plaintext
https://example.com/callback/?code=L4yRDynJso8B9RqYT-a0B1Oct-FNxPzZWd9FfU07QWA
```

--------------------------------

### Authorize API Requests with Access Token

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Use the obtained access token to make authorized calls to Bing Webmaster APIs by including it in the Authorization HTTP header.

```APIDOC
## Authorize Bing Webmaster API Requests

### Description
Include the access token in the `Authorization` HTTP header as a Bearer token to authorize API calls.

### Method
[HTTP method of the API being called, e.g., POST]

### Endpoint
[Full endpoint path of the API being called, e.g., https://www.bing.com/webmaster/api.svc/json/SubmitUrl]

### Headers
- **Authorization**: Bearer [your_access_token]

### Request Body
[Request body specific to the API being called]

### Request Example
```
POST /webmaster/api.svc/json/SubmitUrl HTTP/1.1 
Host: www.bing.com 
Content-Type: application/json 

Authorization: Bearer 2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ 
{
    "siteUrl":"https://www.example.com", 
    "url":"https://www.example.com/url1"
}
```
```

--------------------------------

### Sample JSON Response for Token Request

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

The Bing Webmaster API responds with a JSON object containing the access token, token type, expiration time, and refresh token upon successful authorization code exchange.

```JSON
{
    "access_token": "2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ",
    "token_type": "bearer",
    "expires_in": 3599,
    "refresh_token": "eyJ0eXI7vgiEjC…zqoTD-MRJ9D8J06vp_39oWiA"
}

```

--------------------------------

### Webmaster API Interface Definition

Source: https://learn.microsoft.com/en-us/bingwebmaster/getting-started

Defines the C# interface for the Webmaster API.

```csharp
public interface IWebmasterApi

```

--------------------------------

### Request New Access Token with Refresh Token

Source: https://learn.microsoft.com/en-us/bingwebmaster/oauth2

Send this POST request to the Bing Webmaster authorization server to obtain a new access token using a refresh token. Ensure all parameters are correctly formatted.

```http
POST /webmasters/token HTTP/1.1 
Host: www.bing.com 
Content-Type: application/x-www-form-urlencoded

client_id= 449986cfb7504861996ba2f443210776 & 
client_secret= SP313W-3hpgWXaq_S6P-J2-d1_xsLc4Fs…XOzHGQioA& 
refresh_token= eyJ0eXI7vgiEjC…zqoTD-MRJ9D8J06vp_39oWiA& 
grant_type= refresh_token 

```

--------------------------------

### Bing Webmaster API Capabilities

Source: https://learn.microsoft.com/en-us/bingwebmaster

The Bing Webmaster API enables webmasters to programmatically access information about their website on Bing search and index. It allows retrieval of rank & traffic stats, link details, keyword details, and crawl stats. Additionally, it supports submitting URLs, Sitemaps, and other site details to Bing.

```APIDOC
## Bing Webmaster API Overview

### Description
Provides programmatic access to website data within Bing search and index, including statistics and submission capabilities.

### Capabilities
- Rank & Traffic Stats
- Link Details
- Keyword Details
- Crawl Stats
- URL Submissions
- Sitemap Submissions
```
Tokens:
Raw