# Yelp Search

## Overview

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

## Description

Search Yelp by keyword and location and retrieve paginated business cards with ratings, categories, photos, and sponsored flags.

## 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/yelp/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search cocktail bars in San Francisco

```json
{
  "results": [
    {
      "link": "https://www.yelp.com/adredir?ad_business_id=tGntxs1wgwl2IVcwgfhm0A&campaign_id=219482732&click_origin=search_results&placement=vertical_0&placement_slot=0&redirect_url=https%3A%2F%2Fwww.yelp.com%2Fbiz%2Fcatch-san-francisco-3&request_id=e6a82d0dc569287b&signature=d85aa915d620355289b6c43276f79848a2e1eb5d29f8ad591ba5c13cbbab26c1&slot=0",
      "name": "Catch",
      "alias": "catch-san-francisco-3",
      "is_ad": true,
      "phone": "(415) 431-5000",
      "biz_id": "tGntxs1wgwl2IVcwgfhm0A",
      "rating": 4,
      "picture": "https://s3-media0.fl.yelpcdn.com/bphoto/fkCtr1sSfhz1DY4EjIqoBg/ls.jpg",
      "categories": [
        "Cocktail Bars",
        "Breakfast & Brunch",
        "Coffee & Tea"
      ],
      "price_range": "$$$",
      "review_count": 70
    },
    {
      "link": "https://www.yelp.com/adredir?ad_business_id=e36DPs7qLGswtxbIy9XlVQ&campaign_id=214587588&click_origin=search_results&placement=vertical_0&placement_slot=0&redirect_url=https%3A%2F%2Fwww.yelp.com%2Fbiz%2F200-channels-san-francisco-3&request_id=e6a82d0dc569287b&signature=9a46a6284a56cbf0a0afb36c73bc3ba7c0a2097e6206a3a9f6a5127e12d29a31&slot=1",
      "name": "200 Channels",
      "alias": "200-channels-san-francisco-3",
      "is_ad": true,
      "phone": "+1-415-728-9506",
      "biz_id": "e36DPs7qLGswtxbIy9XlVQ",
      "rating": 4.8,
      "picture": "https://s3-media0.fl.yelpcdn.com/offerphoto/M9FHUPMUcnH82P-qUYCZLg/ls.jpg",
      "categories": [
        "Cabaret",
        "Speakeasies"
      ],
      "price_range": null,
      "review_count": 5
    },
    {
      "link": "https://www.yelp.com/adredir?ad_business_id=9N2SyYEqGTL3pZnhyiFHzg&campaign_id=184504858&click_origin=search_results&placement=vertical_0&placement_slot=0&redirect_url=https%3A%2F%2Fwww.yelp.com%2Fbiz%2Fmoss-beach-distillery-moss-beach&request_id=e6a82d0dc569287b&signature=d6f93a1fce8a79a30db41a99c229bbe3a63fdf8028872bacf03720d274c815cc&slot=2",
      "name": "Moss Beach Distillery",
      "alias": "moss-beach-distillery-moss-beach",
      "is_ad": true,
      "phone": "(650) 728-0220",
      "biz_id": "9N2SyYEqGTL3pZnhyiFHzg",
      "rating": 3.8,
      "picture": "https://s3-media0.fl.yelpcdn.com/bphoto/RDcwAaluiXfR1IDBts78Ug/ls.jpg",
      "categories": [
        "Seafood",
        "Venues & Event Spaces",
        "Bars"
      ],
      "price_range": "$$",
      "review_count": 1964
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "other_pages": [
      2,
      3,
      4,
      5,
      6,
      7,
      8,
      9
    ],
    "total_pages": 9,
    "has_next_page": true,
    "total_results": 0
  }
}
```

## Documentation

## Overview
Search Yelp for local businesses and retrieve paginated listing cards with ratings, review counts, categories, price range, photos, sponsored flags, and business links. Pass a full Yelp search URL (`find_desc` + `find_loc`). Piloterr handles Cloudflare protection via browser rendering and returns structured JSON.

## Quickstart
```
GET https://api.piloterr.com/v2/yelp/search?query=https%3A%2F%2Fwww.yelp.com%2Fsearch%3Ffind_desc%3DCocktail%2BBars%26find_loc%3DSan%2BFrancisco%252C%2BCA
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Yelp search URL (`https://www.yelp.com/search?find_desc=...&find_loc=...`) |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Matching business cards |
| `results[].link` | string | Yelp business or ad redirect URL |
| `results[].name` | string | Business display name |
| `results[].alias` | string | Yelp business slug |
| `results[].biz_id` | string | Yelp business encid |
| `results[].is_ad` | boolean | Whether the card is a sponsored ad |
| `results[].phone` | string \| null | Phone number when shown on the card |
| `results[].rating` | number | Average star rating |
| `results[].review_count` | integer | Total review count |
| `results[].picture` | string | Thumbnail image URL |
| `results[].categories` | array | Category labels |
| `results[].price_range` | string \| null | Price indicator (`$` to `$$$$`) |
| `pagination.current` | integer | Current page |
| `pagination.next` | integer \| null | Next page number |
| `pagination.total_pages` | integer | Total pages |
| `pagination.other_pages` | array | Other page numbers |
| `pagination.has_next_page` | boolean | Whether another page exists |
| `pagination.total_results` | integer | Total results when available |

## Notes
- Sponsored listings (`is_ad: true`) use Yelp ad redirect URLs; organic results link directly to `/biz/` pages.
- `phone` may be `null` on organic cards even when available on the business profile.
- Pass an organic `results[].link` (`/biz/` URL) to **Yelp Business**, or `results[].biz_id` to **Yelp Reviews**.

## 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 Yelp search cards
- Paginate through Yelp result pages programmatically