# Search Yelp businesses by keyword and location

Returns the Yelp businesses that match a search near a location. Use it to find businesses and their Yelp IDs.

Tool `yelp.business.search` on Yelp. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/yelp.business.search/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"location":"Austin, TX","query":"coffee"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/yelp.business.search/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"location": "Austin, TX", "query": "coffee"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/yelp.business.search/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"location": "Austin, TX", "query": "coffee"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "yelp.business.search",
    "input": {
      "location": "Austin, TX",
      "query": "coffee"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `location` | string | Yes |  | Where to search, such as "Austin, TX", a neighborhood or an address. 1 to 500 characters. |
| `query` | string | No |  | What to look for, such as "coffee", a business name or a category. All businesses when left out. 1 to 500 characters. |
| `sort` | string | No |  | Order of the businesses. Yelp's own order is relevance. One of `relevance`, `highest_rating`, `most_reviewed`. |
| `page` | integer | No | `1` | Page of businesses, 10 to a page. A page past the last has no businesses. From 1 to 1001. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### results

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | integer | Yes | Rank among the businesses found, starting at 1 and counting across pages. |
| `title` | string | Yes | Name of the business. |
| `business_id` | string | No | Yelp's ID of the business. The business_id input of yelp.business.reviews. |
| `url` | string | No | Address of the business's page on Yelp. |
| `rating` | number | No | Average review rating, out of 5. |
| `review_count` | integer | No |  |
| `price_range` | string | No | Price level as Yelp shows it, such as "$$". Not parsed. |
| `price_level` | integer | No | Price level from 1, least expensive, to 4, most expensive. |
| `category` | string | No | Kind of business, such as "Coffee Roasteries". |
| `address` | string | No | Street address, without the city, such as "111 Congress Ave". |
| `city` | string | No |  |
| `region` | string | No | State or other region as Yelp writes it, such as "TX". |
| `postal_code` | string | No |  |
| `latitude` | number | No |  |
| `longitude` | number | No |  |
| `phone` | string | No | Phone number as Yelp shows it. |
| `image_url` | string | No | Address of the business's thumbnail image. |
| `snippet` | string | No | Excerpt of a review, as Yelp shows it. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "results": [
    {
      "position": 1,
      "title": "Desnudo Coffee",
      "business_id": "p88l_DLOIB-yL3Ka8GbGDw",
      "url": "https://www.yelp.com/biz/desnudo-coffee-austin-2",
      "rating": 4.6,
      "review_count": 119,
      "price_range": null,
      "price_level": null,
      "category": "Coffee Roasteries",
      "address": "111 Congress Ave",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78701",
      "latitude": 30.26397,
      "longitude": -97.744068,
      "phone": null,
      "image_url": "https://s3-media0.fl.yelpcdn.com/bphoto/oHSoCKvizwSuZwe2J-XK3w/348s.jpg",
      "snippet": "Great coffee spot in a cute trailer in downtown Austin. Went with the popular Brown Sugar Miso Latte..."
    },
    {
      "position": 2,
      "title": "Mazúr Coffee",
      "business_id": "coNV-mKJqjtqmm5RBrAwMA",
      "url": "https://www.yelp.com/biz/maz%C3%BAr-coffee-austin",
      "rating": 4.5,
      "review_count": 38,
      "price_range": null,
      "price_level": null,
      "category": "Coffee & Tea Shops",
      "address": "4207 Medical Pkwy",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78756",
      "latitude": 30.31164,
      "longitude": -97.742306,
      "phone": "(512) 956-7992",
      "image_url": "https://s3-media0.fl.yelpcdn.com/bphoto/cWMp-AQ-naGDo4e8oRaB5g/348s.jpg",
      "snippet": "Overall, it was a solid coffee shop, but I think the aesthetic of the coffee shop is much better..."
    },
    {
      "position": 3,
      "title": "Anderson's Coffee Company",
      "business_id": "YAnvqg699tciMYsqQfqMjw",
      "url": "https://www.yelp.com/biz/andersons-coffee-company-austin",
      "rating": 4.6,
      "review_count": 198,
      "price_range": "$$",
      "price_level": 2,
      "category": "Coffee Roasteries",
      "address": "1601 W 38th St, Ste 2",
      "city": "Austin",
      "region": "TX",
      "postal_code": "78731",
      "latitude": 30.308571,
      "longitude": -97.750328,
      "phone": "(512) 453-1533",
      "image_url": "https://s3-media0.fl.yelpcdn.com/bphoto/gYAuDOnNQ0EAIib1Q30glw/348s.jpg",
      "snippet": "Best place to buy coffee in Austin. I have been enjoying great roasted beans and great coffee at..."
    }
  ]
}
```