# Bing Search

Search Bing and retrieve web search results in JSON format, including advertisements and shopping ads.

## Endpoint

```
GET /v1/b/search/{query}
```

## Description

The Bing Search endpoint allows you to perform web searches and retrieve results from Bing. The query parameter should be a URL-encoded query string that follows Bing's search parameter format.

For reference on Bing search operators, check out [Bing Search Operators Guide](https://seosly.com/blog/bing-search-operators/).

## Authentication

All requests require authentication using the `X-Api-Key` header. See the [Authentication guide](/docs/guides/authentication) for more details.

## Path Parameters

### `query` (required)

**Type:** `string`

A URL-encoded query string. This should follow Bing's search parameter format.

**Examples:**
- `q=search+api`
- `q=instagra`

## Request Headers

### `X-Proxy-Location` (optional)

**Type:** `string`

Specify the proxy location for the search. This determines the geographic location from which the search is performed.

**Allowed values:**
- `EU` - European Union
- `CA` - Canada
- `US` - United States
- `IE` - Ireland
- `GB` - United Kingdom
- `FR` - France
- `DE` - Germany
- `SE` - Sweden
- `IN` - India
- `JP` - Japan
- `KR` - South Korea
- `SG` - Singapore
- `AU` - Australia
- `BR` - Brazil

### `X-User-Agent` (optional)

**Type:** `string`

Specify the device type for the search. Defaults to `desktop` if not provided.

**Allowed values:**
- `desktop` - Desktop browser (default)
- `mobile` - Mobile device

## Request Example

### Using cURL

```bash
curl --request GET \
  --url 'https://api.serply.io/v1/b/search/q=search+api' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Proxy-Location: US' \
  --header 'X-User-Agent: desktop'
```

### Using JavaScript/Node.js

```javascript
const response = await fetch('https://api.serply.io/v1/b/search/q=search+api', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
  }
});
const data = await response.json();
console.log(data);
```

### Using Python

```python
import requests

headers = {
    'X-Api-Key': 'YOUR_API_KEY',
    'X-Proxy-Location': 'US',
    'X-User-Agent': 'desktop'
}

response = requests.get(
    'https://api.serply.io/v1/b/search/q=search+api',
    headers=headers
)
data = response.json()
print(data)
```

## Response

The API returns a JSON object containing search results, advertisements, and shopping ads.

### Response Structure

```json
{
  "ads": [
    {
      "title": "Ad Title",
      "displayUrl": "https://example.com",
      "targetUrl": "https://example.com/target",
      "content": "Ad description...",
      "position": 1,
      "area": "top",
      "realPosition": 1
    }
  ],
  "adsCount": 2,
  "shoppingAds": [
    {
      "title": "Product Title",
      "price": "$99.99",
      "originalPrice": null,
      "advertiser": "Store Name",
      "targetUrl": "https://example.com/product",
      "image": "https://example.com/image.jpg"
    }
  ],
  "results": [
    {
      "title": "Result Title",
      "description": "Result description...",
      "realPosition": 2,
      "link": "https://example.com"
    }
  ],
  "location": {
    "htmlLang": "en"
  },
  "ts": 1.246995449066162,
  "device_region": "",
  "device_type": null,
  "query": "search api"
}
```

### Response Fields

- **`ads`** (array): An array of advertisement objects
  - **`title`** (string): The title of the advertisement
  - **`displayUrl`** (string): The display URL shown to users
  - **`targetUrl`** (string): The actual target URL of the advertisement
  - **`content`** (string): The description/content of the advertisement
  - **`position`** (integer): The position of the ad in the ad list
  - **`area`** (string): The area where the ad appears (`top` or `bottom`)
  - **`realPosition`** (integer): The actual position in the search results
- **`adsCount`** (integer): The total number of advertisements
- **`shoppingAds`** (array): An array of shopping advertisement objects
  - **`title`** (string): The product title
  - **`price`** (string): The product price
  - **`originalPrice`** (string | null): The original price if on sale
  - **`advertiser`** (string): The name of the advertiser/store
  - **`targetUrl`** (string): The URL to the product page
  - **`image`** (string): The product image URL
- **`results`** (array): An array of organic search result objects
  - **`title`** (string): The title of the search result
  - **`description`** (string): The description/snippet of the search result
  - **`realPosition`** (integer): The position in the search results
  - **`link`** (string): The URL of the search result
- **`location`** (object): Location information
  - **`htmlLang`** (string): The HTML language code
- **`ts`** (number): Timestamp of the search
- **`device_region`** (string): Proxy region used, if specified via `X-Proxy-Location`
- **`device_type`** (string | null): The device type used for the search
- **`query`** (string): The search query that was run

### Example Response

```json
{
  "ads": [
    {
      "title": "amazon.in - Buy Mobiles at Amazon",
      "displayUrl": "https://www.amazon.in/Electronics/Home",
      "targetUrl": "https://www.bing.com/aclk?...",
      "content": "Explore latest selection of Mobiles, Tablets, Cameras & More. Pay on Delivery.",
      "position": 1,
      "area": "top",
      "realPosition": 1
    }
  ],
  "adsCount": 2,
  "shoppingAds": [
    {
      "title": "Apple iPhone 13 (128 GB, Green)",
      "price": "₹ 66,990.00",
      "originalPrice": null,
      "advertiser": "Vijay Sales",
      "targetUrl": "https://www.bing.com/aclk?...",
      "image": "data:image/svg+xml;charset=utf8,..."
    }
  ],
  "results": [
    {
      "title": "iPhone 14 and iPhone 14 Plus - Apple (IN)",
      "description": "iPhone 14 has the same super-speedy chip that's in iPhone 13 Pro. A15 Bionic, with a 5‑core …",
      "realPosition": 2,
      "link": "https://www.apple.com/in/iphone-14/"
    }
  ],
  "location": {
    "htmlLang": "en"
  },
  "ts": 1.246995449066162,
  "device_type": null
}
```

## Status Codes

- **200 OK** - Successful response
- **404 Not Found** - The requested resource was not found
- **422 Unprocessable Entity** - The request was well-formed but contains semantic errors
- **429 Too Many Requests** - Rate limit exceeded

## Error Responses

See the [Errors guide](/docs/guides/errors) for information on error response formats.