# Yelp 关键词搜索 API (yelp.search)

- Canonical page: https://everyinfra.com/yelp-api/search
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "yelp", "action": "search", "params": {...}}
- Price: $0.001389 per call ($1.39 per 1,000 requests); failed calls and empty results are not charged
- Returns: list, default 10, max 50 per call
- Mode: sync; add "mode": "async" for slow tasks

Yelp 关键词搜索按 `keyword` 和 `location` 找本地商户，每条结果带名称、链接、评分 `rating` 与满分 `rating_scale`、评价条数、价位档、分类、图片，以及电话、网站、地址、营业时间等资料。它回答「这个地方有哪些这类店、口碑和价位如何」，适合做本地竞品摸底、选址调研和商户名单搭建。

`keyword` 填商户类别或名称，例如 coffee；`location` 填城市、街区或邮编，例如 Austin, TX 或 78701，指商户所在地，不是评论者的位置。默认返回 10 条，最多 50 条。

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=yelp&action=search

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| keyword | not declared | yes | not declared | 本地商户或服务关键词，例如 coffee；需要结合 location，否则默认在 New York 搜索，并非全球检索。 |
| location | not declared | no | not declared | 城市、街区或邮编位置，例如 Austin, TX 或 78701；这是商户所在地，不是评论作者位置。 |
| limit | integer (1–50) | no | 10 | 这次调用最多返回的条数，整数，1–50；不传按默认值，实际返回可能少于这个数。超过上限会在扣费前返回 422。 |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | 该记录在原平台上的唯一标识。仅在同一平台内唯一，跨平台可能重复。 |
| name | 名称。用于账号/商品/商家类能力，指该对象本身的名字。 |
| url | 该记录在原平台上的可访问链接。 |
| rating | 评分。**分制随平台而异**，同一行的 `rating_scale` 给出该平台满分 (多数是 5，Booking/豆瓣/爱奇艺/NAVER 是 10)。跨平台比较前必须先按 rating_scale 换算。直接比数字会得出反的结论。 |
| rating_scale | 上一列 `rating` 的满分。5 表示五星制、10 表示十分制。只在该行有 rating 时出现。 |
| review_count | 评价条数，用于商品/商家类能力。null 表示不公开，不等于 0。 |
| price_range | 价位档（$ 到 $$$$）。 |
| categories | 商家分类。 |
| image_url | 图片链接。多图能力可能返回 image_urls 数组。 |
| platform | 数据来源平台标识，与请求里的 platform 一致（如 xiaohongshu、tiktok）。 |
| phone | 联系电话，原文透传，未做号码格式归一。 |
| website | 账号或商家填写的外链网址。 |
| cuisine | 菜系。 |
| description | 简介或描述，通常比 text 短。 |
| address | 详细地址，原文透传。 |
| city | 城市名，用原平台的语言书写，未做中英归一。 |
| region | 区域。 |
| postal_code | 邮编。 |
| country | 国家或地区。可能是全称也可能是 ISO 代码，取决于平台，未归一。 |
| is_claimed | 商家是否已认领主页。未认领说明店家不运营 Yelp，信息可能过时。 |
| is_verified | 是否为平台认证账号（蓝V等）。null 表示无法判定。 |
| health_score | 卫生检查评分（政府数据，餐厅类才有）。 |
| established_year | 开业年份。 |
| images | 图片链接数组，按平台展示顺序；没有图片时不出现这个字段。 |
| amenities | 设施与服务列表，按 Yelp 页面原文；没有时不出现这个字段。 |
| highlights | Yelp 页面上的商家亮点标签，按页面原文；没有时不出现这个字段。 |
| hours | 营业时间，键是星期几的缩写（如 Mon），值是当天的营业时段原文；没有时不出现这个字段。 |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "yelp",
  "action": "search",
  "params": {
    "keyword": "coffee"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "yelp",
        "action": "search",
        "params": {
            "keyword": "coffee",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 10. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "yelp",
  "action": "search",
  "results": [
    {
      "id": "ten-thousand-coffee-new-york",
      "name": "Ten Thousand Coffee",
      "url": "https://www.yelp.com/biz/ten-thousand-coffee-new-york",
      "rating": 4.4,
      "rating_scale": 5,
      "review_count": 451,
      "price_range": "$$",
      "categories": [
        "Coffee & Tea"
      ],
      "image_url": "https://s3-media0.fl.yelpcdn.com/bphoto/QMmT8iplPLki--HoVPsBtA/ls.jpg",
      "platform": "yelp"
    },
    {
      "id": "remi-flower-and-coffee-new-york-2",
      "name": "Remi Flower & Coffee",
      "url": "https://www.yelp.com/biz/remi-flower-and-coffee-new-york-2",
      "rating": 4.5,
      "rating_scale": 5,
      "review_count": 762,
      "price_range": "$$",
      "categories": [
        "Coffee & Tea",
        "Florists",
        "Floral Designers"
      ],
      "image_url": "https://s3-media0.fl.yelpcdn.com/bphoto/jdhmWm_f2Js83l0prfbzLg/ls.jpg",
      "platform": "yelp"
    }
  ],
  "count": 10,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### 不传 `location` 会搜哪里？

默认在 New York 搜索，并不是全球检索。想搜别的地方，要把城市、街区或邮编填进 `location`，例如 Austin, TX 或 78701。`location` 是商户所在地，不是评论作者的位置。

### 搜索结果和商户主页那一页差在哪？

字段完全一样，差别在入口：这一页按关键词和地点给一批商户，最多 50 条；商户主页那一页按 /biz/ 链接读单个商户。搜索结果已经带地址、电话、营业时间等资料，想再确认某一家时，用结果里的 `url` 去读主页那一页。

### 怎么比较搜出来的商户口碑？

先看 `rating_scale` 确认满分，再比 `rating`，并把 `review_count` 一起看：评价条数很少的评分，参考价值有限。`review_count` 为 null 时是平台没有公开，不等于 0。`is_claimed` 为假表示商家没认领主页，这类店的电话和营业时间最好另找渠道核对。

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=yelp
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md