# Bing Webmaster Tools API Client
[](https://pypi.org/project/bing-webmaster-tools/)
[](https://pypi.org/project/bing-webmaster-tools/)
[](https://github.com/merj/bing-webmaster-tools/blob/main/LICENSE)
[](https://github.com/merj/bing-webmaster-tools/actions/workflows/ci.yml)
An async Python client library for the [Bing Webmaster Tools API](https://learn.microsoft.com/en-us/bingwebmaster/), providing a clean interface for managing websites, analyzing search traffic, handling content submissions, and more.
## Overview
### Description
The Bing Webmaster API Client is a modern, async Python library that provides a comprehensive interface to Bing Webmaster Tools API. The library is designed with a focus on developer experience, type safety, and reliability, offering structured access to all Bing Webmaster Tools features through a clean, domain-driven API.
### Key Features
- **Async/await support** - Built on aiohttp for efficient async operations
- **Type-safe** - Full typing support with runtime validation using Pydantic
- **Domain-driven design** - Operations organized into logical service groups
- **Comprehensive** - Complete coverage of Bing Webmaster Tools API
- **Developer-friendly** - Intuitive interface with detailed documentation
- **Reliable** - Built-in retry logic, rate limiting, and error handling
- **Flexible** - Support for both Pydantic models and dictionaries as input
- **Production-ready** - Extensive logging, testing, and error handling
### Requirements
- Python 3.9 or higher
- Bing Webmaster API key (follow the instructions [here](https://learn.microsoft.com/en-us/bingwebmaster/getting-access#using-api-key))
## Installation
### PyPI Installation
Install the package using pip:
```bash
pip install bing-webmaster-tools
```
## Quick Start
### Basic Setup
1. Get your API key from [Bing Webmaster Tools](https://www.bing.com/webmasters)
2. Set your API key as an environment variable:
```bash
export BING_WEBMASTER_API_KEY=your_api_key_here
```
Or use a .env file:
```env
BING_WEBMASTER_API_KEY=your_api_key_here
```
### Simple Example
Here's a basic example showing how to get site information and analyze traffic:
```python
from bing_webmaster_tools import Settings, BingWebmasterClient
async def main():
# Initialize client with settings from environment
async with BingWebmasterClient(Settings.from_env()) as client:
# Get all sites
sites = await client.sites.get_sites()
if not sites:
print("No sites available")
return
test_site = sites[0].url
print(f"Using site: {test_site}")
# Get traffic stats
traffic_stats = await client.traffic.get_rank_and_traffic_stats(test_site)
print("Traffic Statistics:")
for stat in traffic_stats:
print(f"Date: {stat.date}")
print(f"Clicks: {stat.clicks}")
print(f"Impressions: {stat.impressions}")
if __name__ == "__main__":
import asyncio
asyncio.run(main())
```
### Authentication
The client supports several ways to provide authentication:
1. Environment variables (recommended):
```python
client = BingWebmasterClient(Settings.from_env())
```
2. Direct initialization:
```python
client = BingWebmasterClient(Settings(api_key="your_api_key_here"))
```
3. Configuration file:
```python
from dotenv import load_dotenv
load_dotenv() # Load from .env file
client = BingWebmasterClient(Settings.from_env())
```
## Usage
### Client Initialization
The client can be initialized in several ways:
```python
from bing_webmaster_tools import Settings, BingWebmasterClient
# Using environment variables
async with BingWebmasterClient(Settings.from_env()) as client:
sites = await client.sites.get_sites()
# Direct initialization
settings = Settings(
api_key="your_api_key",
timeout=30, # Custom timeout
max_retries=5 # Custom retry count
)
async with BingWebmasterClient(settings) as client:
sites = await client.sites.get_sites()
# Manual session management
client = BingWebmasterClient(Settings.from_env())
await client.init()
try:
sites = await client.sites.get_sites()
finally:
await client.close()
```
### Configuration Options
The client behavior can be customized through the Settings class:
```python
from bing_webmaster_tools import Settings
settings = Settings(
# Required
api_key="your_api_key", # Also via BING_WEBMASTER_API_KEY env var
# Optional with defaults
base_url="https://ssl.bing.com/webmaster/api.svc/json",
timeout=30, # Request timeout in seconds
max_retries=3, # Maximum number of retry attempts
rate_limit_calls=10, # Number of calls allowed per period
rate_limit_period=1, # Rate limit period in seconds
disable_destructive_operations=False
# Disable destructive operations, if you want to prevent accidental deletions etc.
)
```
Environment variables can be used with the `BING_WEBMASTER_` prefix:
```bash
BING_WEBMASTER_API_KEY=your_api_key
BING_WEBMASTER_TIMEOUT=60
BING_WEBMASTER_MAX_RETRIES=5
```
### Error Handling
The client provides structured error handling:
```python
from bing_webmaster_tools.exceptions import (
BingWebmasterError,
AuthenticationError,
RateLimitError
)
async def handle_api_calls():
try:
await client.sites.get_sites()
except AuthenticationError:
# Handle authentication issues
print("Check your API key")
except RateLimitError:
# Handle rate limiting
print("Too many requests")
except BingWebmasterError as e:
# Handle other API errors
print(f"API error: {e.message}, Status: {e.status_code}")
```
### Rate Limiting
The client includes built-in rate limiting:
- Default: 5 calls per second
- Configurable via settings
- Automatic retry with exponential backoff on rate limit errors
To turn off rate limiting, simply set the rate limit configuration variables to `None`.
## Services
The client provides access to different API functionalities through specialized services.
For full details on available services and methods, refer to the [API documentation](https://learn.microsoft.com/en-us/dotnet/api/microsoft.bing.webmaster.api.interfaces?view=bing-webmaster-dotnet).
### Site Management
Handles site registration, verification, and role management:
```python
# Get all sites
sites = await client.sites.get_sites()
# Add and verify a new site
await client.sites.add_site("https://example.com")
is_verified = await client.sites.verify_site("https://example.com")
# Manage site roles
roles = await client.sites.get_site_roles("https://example.com")
```
### Content Management
Manages URL information and content analysis:
```python
# Get URL information
url_info = await client.content.get_url_info(site_url, page_url)
# Get child URLs information
children = await client.content.get_children_url_info(
site_url,
parent_url,
page=0,
filter_properties=FilterProperties(
crawl_date_filter=CrawlDateFilter.LAST_WEEK,
discovered_date_filter=DiscoveredDateFilter.LAST_MONTH
)
)
```
### Traffic Analysis
Analyzes search traffic and ranking data:
```python
# Get ranking and traffic statistics
stats = await client.traffic.get_rank_and_traffic_stats(site_url)
# Get query-specific statistics
query_stats = await client.traffic.get_query_stats(site_url)
page_stats = await client.traffic.get_page_stats(site_url)
```
### Link Analysis
Manages inbound links and deep links:
```python
# Get link counts
link_counts = await client.links.get_link_counts(site_url)
# Get URL-specific links
url_links = await client.links.get_url_links(site_url, url)
# Get connected pages
connected = await client.links.get_connected_pages(site_url)
```
### Keyword Analysis
Analyzes keyword performance:
```python
# Get keyword data
keyword_data = await client.keywords.get_keyword(
query="python programming",
country="us",
language="en-US",
start_date=datetime.now() - timedelta(days=30),
end_date=datetime.now()
)
# Get related keywords
related = await client.keywords.get_related_keywords(
query="python",
country="us",
language="en-US",
start_date=datetime.now() - timedelta(days=30),
end_date=datetime.now()
)
```
### Content Blocking
Manages URL blocking and page preview settings:
```python
# Block a URL
await client.blocking.add_blocked_url(
site_url,
blocked_url,
entity_type=BlockedUrl.BlockedUrlEntityType.PAGE
)
# Manage page previews
await client.blocking.add_page_preview_block(
site_url,
url,
reason=BlockReason.COPYRIGHT
)
```
### URL Management
Handles URL parameters and normalization:
```python
# Manage query parameters
params = await client.urls.get_query_parameters(site_url)
await client.urls.add_query_parameter(site_url, "sort")
await client.urls.enable_disable_query_parameter(site_url, "sort", True)
```
### Submission Service
Handles URL and content submission:
```python
# Submit URLs
await client.submission.submit_url(site_url, page_url)
await client.submission.submit_url_batch(site_url, [url1, url2])
# Manage feeds
await client.submission.submit_feed(site_url, feed_url)
quota = await client.submission.get_url_submission_quota(site_url)
```
### Crawling Service
Manages crawl settings and monitoring:
```python
# Get and update crawl settings
settings = await client.crawling.get_crawl_settings(site_url)
await client.crawling.save_crawl_settings(
site_url,
CrawlSetting(
crawl_boost_available=True,
crawl_boost_enabled=True,
crawl_rate=[5] * 24 # 24 hourly rates
)
)
# Get crawl statistics
stats = await client.crawling.get_crawl_stats(
site_url,
start_date=datetime.now() - timedelta(days=30),
end_date=datetime.now()
)
# Get crawl issues
issues = await client.crawling.get_crawl_issues(site_url)
```
### Regional Settings
Manages country and region-specific settings:
```python
# Get current settings
settings = await client.regional.get_country_region_settings(site_url)
# Add new regional settings
await client.regional.add_country_region_settings(
site_url,
CountryRegionSettings(
date=datetime.now(),
two_letter_iso_country_code="US",
type=CountryRegionSettingsType.DOMAIN,
url="https://example.com"
)
)
# Remove regional settings
await client.regional.remove_country_region_settings(
site_url,
settings # Existing settings to remove
)
```
## Development
### Development Installation
To install from source for development:
```bash
# Clone the repository
git clone https://github.com/merj/bing-webmaster-tools
cd bing-webmaster-tools
# Install poetry if you haven't already
pip install poetry
# Install dependencies and setup development environment
poetry install
```
Raw data
{
"_id": null,
"home_page": "https://github.com/merj/bing-webmaster-tools",
"name": "bing-webmaster-tools",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "bing, webmaster, seo, api, sdk",
"author": "Ryan Siddle",
"author_email": "ryan.siddle@merj.com",
"download_url": "https://files.pythonhosted.org/packages/c0/4e/342bf77950c211d0554813d3ca69bd75ad98ab1d0039afa7c68d85af04b2/bing_webmaster_tools-1.1.0.tar.gz",
"platform": null,
"description": "# Bing Webmaster Tools API Client\n\n[](https://pypi.org/project/bing-webmaster-tools/)\n[](https://pypi.org/project/bing-webmaster-tools/)\n[](https://github.com/merj/bing-webmaster-tools/blob/main/LICENSE)\n[](https://github.com/merj/bing-webmaster-tools/actions/workflows/ci.yml)\n\n\nAn async Python client library for the [Bing Webmaster Tools API](https://learn.microsoft.com/en-us/bingwebmaster/), providing a clean interface for managing websites, analyzing search traffic, handling content submissions, and more.\n\n## Overview\n\n### Description\nThe Bing Webmaster API Client is a modern, async Python library that provides a comprehensive interface to Bing Webmaster Tools API. The library is designed with a focus on developer experience, type safety, and reliability, offering structured access to all Bing Webmaster Tools features through a clean, domain-driven API.\n\n### Key Features\n- **Async/await support** - Built on aiohttp for efficient async operations\n- **Type-safe** - Full typing support with runtime validation using Pydantic\n- **Domain-driven design** - Operations organized into logical service groups\n- **Comprehensive** - Complete coverage of Bing Webmaster Tools API\n- **Developer-friendly** - Intuitive interface with detailed documentation\n- **Reliable** - Built-in retry logic, rate limiting, and error handling\n- **Flexible** - Support for both Pydantic models and dictionaries as input\n- **Production-ready** - Extensive logging, testing, and error handling\n\n### Requirements\n- Python 3.9 or higher\n- Bing Webmaster API key (follow the instructions [here](https://learn.microsoft.com/en-us/bingwebmaster/getting-access#using-api-key))\n\n## Installation\n\n### PyPI Installation\nInstall the package using pip:\n```bash\npip install bing-webmaster-tools\n```\n\n## Quick Start\n\n### Basic Setup\n1. Get your API key from [Bing Webmaster Tools](https://www.bing.com/webmasters)\n\n2. Set your API key as an environment variable:\n```bash\nexport BING_WEBMASTER_API_KEY=your_api_key_here\n```\n\nOr use a .env file:\n```env\nBING_WEBMASTER_API_KEY=your_api_key_here\n```\n\n### Simple Example\nHere's a basic example showing how to get site information and analyze traffic:\n\n```python\nfrom bing_webmaster_tools import Settings, BingWebmasterClient\n\n\nasync def main():\n # Initialize client with settings from environment\n async with BingWebmasterClient(Settings.from_env()) as client:\n # Get all sites\n sites = await client.sites.get_sites()\n if not sites:\n print(\"No sites available\")\n return\n\n test_site = sites[0].url\n print(f\"Using site: {test_site}\")\n\n # Get traffic stats\n traffic_stats = await client.traffic.get_rank_and_traffic_stats(test_site)\n print(\"Traffic Statistics:\")\n for stat in traffic_stats:\n print(f\"Date: {stat.date}\")\n print(f\"Clicks: {stat.clicks}\")\n print(f\"Impressions: {stat.impressions}\")\n\n\nif __name__ == \"__main__\":\n import asyncio\n\n asyncio.run(main())\n```\n\n### Authentication\nThe client supports several ways to provide authentication:\n\n1. Environment variables (recommended):\n```python\nclient = BingWebmasterClient(Settings.from_env())\n```\n\n2. Direct initialization:\n```python\nclient = BingWebmasterClient(Settings(api_key=\"your_api_key_here\"))\n```\n\n3. Configuration file:\n```python\nfrom dotenv import load_dotenv\nload_dotenv() # Load from .env file\nclient = BingWebmasterClient(Settings.from_env())\n```\n\n## Usage\n\n### Client Initialization\nThe client can be initialized in several ways:\n\n```python\nfrom bing_webmaster_tools import Settings, BingWebmasterClient\n\n# Using environment variables\nasync with BingWebmasterClient(Settings.from_env()) as client:\n sites = await client.sites.get_sites()\n\n# Direct initialization\nsettings = Settings(\n api_key=\"your_api_key\",\n timeout=30, # Custom timeout\n max_retries=5 # Custom retry count\n)\nasync with BingWebmasterClient(settings) as client:\n sites = await client.sites.get_sites()\n\n# Manual session management\nclient = BingWebmasterClient(Settings.from_env())\nawait client.init()\ntry:\n sites = await client.sites.get_sites()\nfinally:\n await client.close()\n```\n\n### Configuration Options\nThe client behavior can be customized through the Settings class:\n\n```python\nfrom bing_webmaster_tools import Settings\n\nsettings = Settings(\n # Required\n api_key=\"your_api_key\", # Also via BING_WEBMASTER_API_KEY env var\n\n # Optional with defaults\n base_url=\"https://ssl.bing.com/webmaster/api.svc/json\",\n timeout=30, # Request timeout in seconds\n max_retries=3, # Maximum number of retry attempts\n rate_limit_calls=10, # Number of calls allowed per period\n rate_limit_period=1, # Rate limit period in seconds\n disable_destructive_operations=False\n # Disable destructive operations, if you want to prevent accidental deletions etc. \n)\n```\n\nEnvironment variables can be used with the `BING_WEBMASTER_` prefix:\n```bash\nBING_WEBMASTER_API_KEY=your_api_key\nBING_WEBMASTER_TIMEOUT=60\nBING_WEBMASTER_MAX_RETRIES=5\n```\n\n### Error Handling\nThe client provides structured error handling:\n\n```python\nfrom bing_webmaster_tools.exceptions import (\n BingWebmasterError,\n AuthenticationError,\n RateLimitError\n)\n\n\nasync def handle_api_calls():\n try:\n await client.sites.get_sites()\n except AuthenticationError:\n # Handle authentication issues\n print(\"Check your API key\")\n except RateLimitError:\n # Handle rate limiting\n print(\"Too many requests\")\n except BingWebmasterError as e:\n # Handle other API errors\n print(f\"API error: {e.message}, Status: {e.status_code}\")\n```\n\n### Rate Limiting\nThe client includes built-in rate limiting:\n- Default: 5 calls per second\n- Configurable via settings\n- Automatic retry with exponential backoff on rate limit errors\n\nTo turn off rate limiting, simply set the rate limit configuration variables to `None`.\n\n## Services\n\nThe client provides access to different API functionalities through specialized services.\nFor full details on available services and methods, refer to the [API documentation](https://learn.microsoft.com/en-us/dotnet/api/microsoft.bing.webmaster.api.interfaces?view=bing-webmaster-dotnet).\n\n### Site Management\nHandles site registration, verification, and role management:\n\n```python\n# Get all sites\nsites = await client.sites.get_sites()\n\n# Add and verify a new site\nawait client.sites.add_site(\"https://example.com\")\nis_verified = await client.sites.verify_site(\"https://example.com\")\n\n# Manage site roles\nroles = await client.sites.get_site_roles(\"https://example.com\")\n```\n\n### Content Management\nManages URL information and content analysis:\n\n```python\n# Get URL information\nurl_info = await client.content.get_url_info(site_url, page_url)\n\n# Get child URLs information\nchildren = await client.content.get_children_url_info(\n site_url,\n parent_url,\n page=0,\n filter_properties=FilterProperties(\n crawl_date_filter=CrawlDateFilter.LAST_WEEK,\n discovered_date_filter=DiscoveredDateFilter.LAST_MONTH\n )\n)\n```\n\n### Traffic Analysis\nAnalyzes search traffic and ranking data:\n\n```python\n# Get ranking and traffic statistics\nstats = await client.traffic.get_rank_and_traffic_stats(site_url)\n\n# Get query-specific statistics\nquery_stats = await client.traffic.get_query_stats(site_url)\npage_stats = await client.traffic.get_page_stats(site_url)\n```\n\n### Link Analysis\nManages inbound links and deep links:\n\n```python\n# Get link counts\nlink_counts = await client.links.get_link_counts(site_url)\n\n# Get URL-specific links\nurl_links = await client.links.get_url_links(site_url, url)\n\n# Get connected pages\nconnected = await client.links.get_connected_pages(site_url)\n```\n\n### Keyword Analysis\nAnalyzes keyword performance:\n\n```python\n# Get keyword data\nkeyword_data = await client.keywords.get_keyword(\n query=\"python programming\",\n country=\"us\",\n language=\"en-US\",\n start_date=datetime.now() - timedelta(days=30),\n end_date=datetime.now()\n)\n\n# Get related keywords\nrelated = await client.keywords.get_related_keywords(\n query=\"python\",\n country=\"us\",\n language=\"en-US\",\n start_date=datetime.now() - timedelta(days=30),\n end_date=datetime.now()\n)\n```\n\n### Content Blocking\nManages URL blocking and page preview settings:\n\n```python\n# Block a URL\nawait client.blocking.add_blocked_url(\n site_url,\n blocked_url,\n entity_type=BlockedUrl.BlockedUrlEntityType.PAGE\n)\n\n# Manage page previews\nawait client.blocking.add_page_preview_block(\n site_url,\n url,\n reason=BlockReason.COPYRIGHT\n)\n```\n\n### URL Management\nHandles URL parameters and normalization:\n\n```python\n# Manage query parameters\nparams = await client.urls.get_query_parameters(site_url)\nawait client.urls.add_query_parameter(site_url, \"sort\")\nawait client.urls.enable_disable_query_parameter(site_url, \"sort\", True)\n```\n\n### Submission Service\nHandles URL and content submission:\n\n```python\n# Submit URLs\nawait client.submission.submit_url(site_url, page_url)\nawait client.submission.submit_url_batch(site_url, [url1, url2])\n\n# Manage feeds\nawait client.submission.submit_feed(site_url, feed_url)\nquota = await client.submission.get_url_submission_quota(site_url)\n```\n\n### Crawling Service\nManages crawl settings and monitoring:\n\n```python\n# Get and update crawl settings\nsettings = await client.crawling.get_crawl_settings(site_url)\nawait client.crawling.save_crawl_settings(\n site_url,\n CrawlSetting(\n crawl_boost_available=True,\n crawl_boost_enabled=True,\n crawl_rate=[5] * 24 # 24 hourly rates\n )\n)\n\n# Get crawl statistics\nstats = await client.crawling.get_crawl_stats(\n site_url,\n start_date=datetime.now() - timedelta(days=30),\n end_date=datetime.now()\n)\n\n# Get crawl issues\nissues = await client.crawling.get_crawl_issues(site_url)\n```\n\n### Regional Settings\nManages country and region-specific settings:\n\n```python\n# Get current settings\nsettings = await client.regional.get_country_region_settings(site_url)\n\n# Add new regional settings\nawait client.regional.add_country_region_settings(\n site_url,\n CountryRegionSettings(\n date=datetime.now(),\n two_letter_iso_country_code=\"US\",\n type=CountryRegionSettingsType.DOMAIN,\n url=\"https://example.com\"\n )\n)\n\n# Remove regional settings\nawait client.regional.remove_country_region_settings(\n site_url,\n settings # Existing settings to remove\n)\n```\n\n## Development\n\n### Development Installation\nTo install from source for development:\n\n```bash\n# Clone the repository\ngit clone https://github.com/merj/bing-webmaster-tools\ncd bing-webmaster-tools\n\n# Install poetry if you haven't already\npip install poetry\n\n# Install dependencies and setup development environment\npoetry install\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Python wrapper for the Bing Webmaster Tools API",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/merj/bing-webmaster-tools",
"Repository": "https://github.com/merj/bing-webmaster-tools"
},
"split_keywords": [
"bing",
" webmaster",
" seo",
" api",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4dd12c28e9a2ae9f415ec7e368dfb6519dd5302b17adb66cdcf2bfc5e0244d6e",
"md5": "fedb91f1e4013b4fc915914948837bca",
"sha256": "d4677c579d7ef892df80e45692a2f2fa43e0a911a9fac85ab581486e6715108b"
},
"downloads": -1,
"filename": "bing_webmaster_tools-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fedb91f1e4013b4fc915914948837bca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 38572,
"upload_time": "2024-11-08T10:57:18",
"upload_time_iso_8601": "2024-11-08T10:57:18.355394Z",
"url": "https://files.pythonhosted.org/packages/4d/d1/2c28e9a2ae9f415ec7e368dfb6519dd5302b17adb66cdcf2bfc5e0244d6e/bing_webmaster_tools-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c04e342bf77950c211d0554813d3ca69bd75ad98ab1d0039afa7c68d85af04b2",
"md5": "aeb07afaa2becab3bd5da1bae2e6ff4f",
"sha256": "09ea7496a29122c8fc44594b4bc86c86ba1205e7841e16777efbb4585ee5100f"
},
"downloads": -1,
"filename": "bing_webmaster_tools-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "aeb07afaa2becab3bd5da1bae2e6ff4f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 28752,
"upload_time": "2024-11-08T10:57:20",
"upload_time_iso_8601": "2024-11-08T10:57:20.016349Z",
"url": "https://files.pythonhosted.org/packages/c0/4e/342bf77950c211d0554813d3ca69bd75ad98ab1d0039afa7c68d85af04b2/bing_webmaster_tools-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-08 10:57:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "merj",
"github_project": "bing-webmaster-tools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bing-webmaster-tools"
}
JSON
