# 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
```
## Examples
Look under the [examples](./examples) subdirectory to see boilerplate scripts which can help you get started. These assume you are using the environment variable `BING_WEBMASTER_API_KEY` as described in the [Basic Setup](#basic-setup).
### 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).
## 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/46/92/3090bc49d677e4227159a6e343216b41e06ad1822a684cdc2b35f70adf7d/bing_webmaster_tools-1.1.2.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## Examples\n\nLook under the [examples](./examples) subdirectory to see boilerplate scripts which can help you get started. These assume you are using the environment variable `BING_WEBMASTER_API_KEY` as described in the [Basic Setup](#basic-setup).\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\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.2",
"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": "736e00ca5addf6845af8d2cc6f0d884d60584be31956110a2be9e26cbc66c5c1",
"md5": "def08e31de6b35eca7f04b24866fdaa7",
"sha256": "1db4e475ba65591de7cb38eb204393c3a02bb6d723712dab9e6d1f5277571ff9"
},
"downloads": -1,
"filename": "bing_webmaster_tools-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "def08e31de6b35eca7f04b24866fdaa7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 37360,
"upload_time": "2025-01-23T22:48:31",
"upload_time_iso_8601": "2025-01-23T22:48:31.878947Z",
"url": "https://files.pythonhosted.org/packages/73/6e/00ca5addf6845af8d2cc6f0d884d60584be31956110a2be9e26cbc66c5c1/bing_webmaster_tools-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46923090bc49d677e4227159a6e343216b41e06ad1822a684cdc2b35f70adf7d",
"md5": "4745a92770b75fd42f49fabab7f65d1a",
"sha256": "636fea2c6ada63b5c03a3c6eb605cc14fb320eaa71fce5f91b8a0c6c7951b24d"
},
"downloads": -1,
"filename": "bing_webmaster_tools-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4745a92770b75fd42f49fabab7f65d1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 25540,
"upload_time": "2025-01-23T22:48:35",
"upload_time_iso_8601": "2025-01-23T22:48:35.543017Z",
"url": "https://files.pythonhosted.org/packages/46/92/3090bc49d677e4227159a6e343216b41e06ad1822a684cdc2b35f70adf7d/bing_webmaster_tools-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-23 22:48:35",
"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
