# Yellowpages Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/yellowpages/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/yellowpages-search |

## Description

Search Yellow Pages businesses from a full search URL and retrieve names, phones, addresses, ratings, opening hours, and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/yellowpages/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search plumbers in Los Angeles

```json
{
  "results": [
    {
      "url": "https://www.yellowpages.com/los-angeles-ca/mip/anawalt-lumber-13945594?lid=1002108313121",
      "name": "Anawalt Lumber",
      "phone": "(844) 699-3144",
      "postal_code": "90064",
      "rating_value": 4.8,
      "review_count": 5,
      "opening_hours": [
        "Mo-Fr 06:00-20:00",
        "Sa 08:00-20:00",
        "Su 09:00-18:00"
      ],
      "address_region": "CA",
      "street_address": "11060 W Pico Blvd",
      "address_country": "US",
      "address_locality": "Los Angeles"
    },
    {
      "url": "https://www.yellowpages.com/los-angeles-ca/mip/emergency-rooter-542379108?lid=1002116238752",
      "name": "Emergency Rooter",
      "phone": "(424) 252-2969",
      "postal_code": "90019",
      "rating_value": 4.5,
      "review_count": 2,
      "opening_hours": [
        "Mo-Su"
      ],
      "address_region": "CA",
      "street_address": "1319 S La Brea Ave",
      "address_country": "US",
      "address_locality": "Los Angeles"
    },
    {
      "url": "https://www.yellowpages.com/los-angeles-ca/mip/rooter-star-546734508?lid=1002194168683",
      "name": "Rooter Star",
      "phone": "(888) 574-3053",
      "postal_code": "90019",
      "rating_value": 4.33,
      "review_count": 3,
      "address_region": "CA",
      "street_address": "1319 S La Brea Ave",
      "address_country": "US",
      "address_locality": "Los Angeles"
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "next_url": "https://www.yellowpages.com/los-angeles-ca/plumbers?page=2",
    "per_page": 30,
    "other_pages": [
      2,
      3,
      4,
      5
    ],
    "total_count": 1401,
    "total_pages": 47,
    "has_next_page": true
  }
}
```

## Documentation

## Overview
Extract business listing cards from any Yellow Pages search results page. Returns structured results with name, phone, address components, ratings, review counts, opening hours, and pagination metadata.

Yellow Pages search pages are JavaScript single-page applications. Listing cards load dynamically after the initial HTML shell. A plain HTTP request returns an empty page skeleton. Piloterr uses **website rendering** to execute JavaScript, wait for business cards to render, and extract structured JSON from the live DOM.

## Quickstart
```
GET https://api.piloterr.com/v2/yellowpages/search?query=https://www.yellowpages.com/los-angeles-ca/plumbers
```

Copy the full URL from yellowpages.com. Use `?page=2` or `pagination.next_url` for pagination.

## Supported URL formats
| Format | Example |
|---|---|
| Category in city | `https://www.yellowpages.com/los-angeles-ca/plumbers` |
| Paginated search | `https://www.yellowpages.com/los-angeles-ca/plumbers?page=2` |

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Yellow Pages search URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Business listing cards |
| `results[].url` | string | Business profile URL |
| `results[].name` | string | Business name |
| `results[].phone` | string \| null | Formatted phone number |
| `results[].street_address` | string \| null | Street line |
| `results[].address_locality` | string \| null | City |
| `results[].address_region` | string \| null | State code |
| `results[].postal_code` | string \| null | ZIP code |
| `results[].address_country` | string \| null | Country code |
| `results[].rating_value` | number \| null | Average rating (0-5) |
| `results[].review_count` | integer \| null | Number of reviews |
| `results[].opening_hours` | array | Opening hours strings (Schema.org format) |
| `pagination.current` | integer | Current page number |
| `pagination.next` | integer \| null | Next page number |
| `pagination.next_url` | string \| null | Next page URL |
| `pagination.total_pages` | integer | Total pages |
| `pagination.total_count` | integer | Total matching listings |
| `pagination.per_page` | integer | Results on this page |
| `pagination.other_pages` | array | Other page numbers |
| `pagination.has_next_page` | boolean | Whether a next page exists |

## Notes
- Targets **yellowpages.com** (US).
- `opening_hours` and rating fields may be absent on some cards.
- Pass `results[].url` to **Yellowpages Business** for website, categories, and full rating details.

## Main use cases
- Build local business lead lists by category and city
- Monitor competitor ratings and review counts at scale
- Feed sales prospecting tools with Yellow Pages search cards
- Paginate through Yellow Pages result pages programmatically