Skip to main content
GET
Search businesses
Returns one page of up to ten organic businesses in Yelp’s ranking, sponsored listings in ads, Yelp’s filter options for the search and pagination metadata. Credits: 15 per page with results. Empty searches, failed requests and cache hits (X-Cache: HIT) are unbilled. location is required (at most 128 characters). page is 1 to 11. features and price are comma lists; every filter must be applied by Yelp or the request returns 422 filter_not_applied. query_matched: false means Yelp could not place the query: it shows either its broader ranking (billed) or its own no-results page (results: [], free).

Errors

Invalid, unsupported or malformed parameters received by the API gateway return 422. Ingress parsing happens first: a bare ; separates parameters, so location=SF;page=2 can perform a billed page-2 search. Use & between parameters and %3B for a semicolon inside a value; see the query encoding notes. A location Yelp cannot find returns 400 invalid_location. Unavailable source content returns 503 instead of a billable empty result. A key without the yelp scope returns 403. See the overview for markets, filters, fields and pagination.

Authorizations

X-API-Key
string
header
required

Query Parameters

location
string
required

Where to search, as typed into Yelp: city, neighbourhood, address or postcode.

Required string length: 1 - 128
query
string | null

What to search for (e.g. pizza, plumbers). Optional when category is set.

Maximum string length: 128
market
enum<string>
default:us

Yelp site to search; see /markets.

Available options:
us,
ca
category
string | null

Yelp category alias, e.g. pizza, coffee, plumbing.

Pattern: ^[a-z0-9_-]{1,64}$
sort_by
enum<string>
default:recommended
Available options:
recommended,
rating,
review_count
price
string | null

Comma-separated price levels 1-4 ($ to $$$$).

Pattern: ^[1-4](,[1-4]){0,3}$
features
string | null

Comma-separated refinements: delivery, takeout, reservations, outdoor_seating, good_for_kids, dogs_allowed, free_wifi, wheelchair_accessible.

page
integer
default:1

1-based page, ten businesses each; pages 1-11.

Required range: 1 <= x <= 11

Response

Successful Response

market
string
required
query
string | null
required
location
string
required
location_resolved
YelpResolvedLocation · object
required
query_matched
boolean
required

False when Yelp could not place the query; results are then Yelp's broader ranking for the location, as Yelp shows them.

total_results
integer
required

Yelp's reported total; at most 110 are browsable.

page
integer
required
page_size
integer
required
total_pages
integer
required
has_next_page
boolean
required
results
YelpBusiness · object[]
required
ads
YelpBusiness · object[]
required
filters
Filters · object
required
source_url
string
required
fetched_at
string
required
fetched_utc
number
required
did_you_mean
string | null
next_page
integer | null