# Yellow Pages Business Search API Documentation

Search public Yellow Pages businesses by term and place (City, ST or ZIP), up to 30 per page: id, name, categories, rating, review count, address, phone, website, open status and snippet. Costs 12 credits per request. Failed requests are free.

- **Documentation:** [https://scrappa.co/docs/yellowpages-api/yellowpages_search](https://scrappa.co/docs/yellowpages-api/yellowpages_search)
- **API group:** Yellow Pages API
- **Endpoint:** `GET https://scrappa.co/api/yellowpages/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | Yes | What to look for, 2 to 100 characters. Example: plumbers. |
| `location` | string | Yes | US city and state or ZIP code, 2 to 100 characters. Example: Austin, TX or 90210. |
| `page` | integer | No | Page number, 1 to 50. Each page holds up to 30 businesses. A page past the end returns an empty list and the real total. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/yellowpages/search?query=plumbers&location=Austin%2C+TX"
```

## Example response

```json
{
    "success": true,
    "data": {
        "query": "plumbers",
        "location": "Austin, TX",
        "page": 1,
        "per_page": 30,
        "total": 495,
        "has_more": true,
        "next_page": 2,
        "results": [
            {
                "id": "/austin-tx/mip/clarke-kent-plumbing-10674347",
                "ypid": "10674347",
                "name": "Clarke Kent Plumbing",
                "url": "https://www.yellowpages.com/austin-tx/mip/clarke-kent-plumbing-10674347",
                "categories": [
                    "Plumbers",
                    "Plumbing-Drain & Sewer Cleaning"
                ],
                "rating": 2.87,
                "review_count": 15,
                "address": {
                    "street": "1408 W Ben White Blvd",
                    "city": "Austin",
                    "region": "TX",
                    "postal_code": "78704",
                    "formatted": "1408 W Ben White Blvd, Austin, TX 78704"
                },
                "phone": "(512) 766-0970",
                "website": "http://www.clarkekentplumbing.com",
                "coordinates": null,
                "years_in_business": 40,
                "open_status": "closed now",
                "hours": [
                    "Mo-Fr 09:00-17:00"
                ],
                "snippet": "Josh was wonderful and very professional."
            }
        ]
    },
    "meta": {
        "endpoint_family": "business_search",
        "billable": true,
        "credits": 12
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A required parameter is missing or invalid. This response is not billable. |
| 502 | Upstream Unavailable | Yellow Pages did not answer with usable data. This response is not billable. Retry later. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)