openapi: 3.1.0
info:
title: Yelp Fusion API
description: >-
The Yelp Fusion API provides programmatic access to Yelp's database of
local businesses, reviews, events, categories, and conversational AI search.
This definition documents the public Fusion REST endpoints: business search
and discovery, business details, reviews, autocomplete, phone search,
business match, events, categories, and the Yelp Fusion AI chat endpoint.
Authentication is via a bearer API key passed in the Authorization header.
version: "3.0"
contact:
name: Yelp Developer
url: https://docs.developer.yelp.com/
termsOfService: https://docs.developer.yelp.com/docs/policies
servers:
- url: https://api.yelp.com
description: Yelp Fusion API base URL
x-generated-from: https://docs.developer.yelp.com/reference
x-generated-by: api-evangelist-pipeline-2026-06
tags:
- name: Businesses
description: Search, match, and retrieve local business data
- name: Reviews
description: Business review excerpts and ratings
- name: Events
description: Local event search and details
- name: Categories
description: Yelp business category taxonomy
- name: AI
description: Conversational Yelp Fusion AI search and chat
security:
- bearerAuth: []
paths:
/v3/businesses/search:
get:
tags: [Businesses]
operationId: searchBusinesses
summary: Search Businesses
description: >-
Returns up to 240 businesses based on the provided search criteria.
Either location or a latitude/longitude pair is required.
parameters:
- name: location
in: query
description: Geographic area to search. Required if latitude and longitude are not provided.
schema: {type: string, maxLength: 250}
example: example
- name: latitude
in: query
description: Latitude of the search center. Required if location is not provided.
schema: {type: number, format: double, minimum: -90, maximum: 90}
example: 37.7867
- name: longitude
in: query
description: Longitude of the search center. Required if location is not provided.
schema: {type: number, format: double, minimum: -180, maximum: 180}
example: -122.4112
- name: term
in: query
description: Search term, such as "food" or a business name.
schema: {type: string, maxLength: 300}
example: example
- name: radius
in: query
description: Search radius in meters. Maximum 40000.
schema: {type: integer, minimum: 0, maximum: 40000}
example: 1
- name: categories
in: query
description: Comma-delimited list of category aliases to filter by.
schema: {type: string}
example: example
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
- name: price
in: query
description: Comma-delimited list of price levels (1, 2, 3, 4).
schema: {type: string}
example: $$
- name: open_now
in: query
description: Return only businesses open at the time of the request.
schema: {type: boolean}
example: true
- name: open_at
in: query
description: Return businesses open at the given Unix timestamp.
schema: {type: integer}
example: 1
- name: attributes
in: query
description: Comma-delimited list of business attributes to filter by.
schema: {type: string}
example: example
- name: sort_by
in: query
description: Sort mode for results.
schema:
type: string
enum: [best_match, rating, review_count, distance]
default: best_match
example: best_match
- name: limit
in: query
description: Number of results to return.
schema: {type: integer, minimum: 0, maximum: 50, default: 20}
example: 1
- name: offset
in: query
description: Offset into the list of returned results.
schema: {type: integer, minimum: 0, maximum: 1000}
example: 1
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessSearchResponse'
examples:
SearchBusinesses200Example:
summary: Default searchBusinesses 200 response
x-microcks-default: true
value:
total: 240
businesses:
- id: gR9DTbKCON2g1Z23bWcEpQ
alias: rickys-tacos-san-francisco
name: Ricky's Tacos
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
is_closed: false
url: https://www.yelp.com/biz/rickys-tacos-san-francisco
review_count: 1289
categories:
- {}
rating: 4.5
coordinates:
latitude: 37.7867
longitude: -122.4112
transactions:
- pickup
price: $$
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address: {}
cross_streets: example
phone: '+14159083801'
display_phone: (415) 908-3801
distance: 1503.4
attributes: {}
region:
center:
latitude: 37.7867
longitude: -122.4112
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/businesses/search/phone:
get:
tags: [Businesses]
operationId: searchBusinessesByPhone
summary: Search Businesses By Phone
description: Returns businesses associated with the given phone number.
parameters:
- name: phone
in: query
required: true
description: Phone number in the form +[country code][number], e.g. +14159083801.
schema: {type: string, pattern: "^[0-9 +()-.x/]+$", minLength: 1, maxLength: 32}
example: '+14159083801'
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessSearchResponse'
examples:
SearchBusinessesByPhone200Example:
summary: Default searchBusinessesByPhone 200 response
x-microcks-default: true
value:
total: 240
businesses:
- id: gR9DTbKCON2g1Z23bWcEpQ
alias: rickys-tacos-san-francisco
name: Ricky's Tacos
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
is_closed: false
url: https://www.yelp.com/biz/rickys-tacos-san-francisco
review_count: 1289
categories:
- {}
rating: 4.5
coordinates:
latitude: 37.7867
longitude: -122.4112
transactions:
- pickup
price: $$
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address: {}
cross_streets: example
phone: '+14159083801'
display_phone: (415) 908-3801
distance: 1503.4
attributes: {}
region:
center:
latitude: 37.7867
longitude: -122.4112
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/businesses/matches:
get:
tags: [Businesses]
operationId: matchBusinesses
summary: Match Businesses
description: >-
Matches the supplied business attributes against businesses on Yelp,
returning the best candidate matches. Useful for resolving your own
records to a Yelp business id.
parameters:
- name: name
in: query
required: true
description: Business name.
schema: {type: string, maxLength: 64}
example: Ricky's Tacos
- name: address1
in: query
required: true
description: First line of the business address.
schema: {type: string, maxLength: 64}
example: 350 Mission St
- name: address2
in: query
description: Second line of the business address.
schema: {type: string, maxLength: 64}
example: ''
- name: address3
in: query
description: Third line of the business address.
schema: {type: string, maxLength: 64}
example: ''
- name: city
in: query
required: true
description: City of the business.
schema: {type: string, minLength: 1, maxLength: 64}
example: San Francisco
- name: state
in: query
required: true
description: ISO 3166-2 state code of the business.
schema: {type: string, minLength: 1, maxLength: 3}
example: CA
- name: country
in: query
required: true
description: ISO 3166-1 alpha-2 country code of the business.
schema: {type: string, minLength: 2, maxLength: 2}
example: US
- name: postal_code
in: query
description: Postal/ZIP code of the business.
schema: {type: string, maxLength: 12}
example: example
- name: latitude
in: query
description: Latitude of the business.
schema: {type: number, format: double, minimum: -90, maximum: 90}
example: 37.7867
- name: longitude
in: query
description: Longitude of the business.
schema: {type: number, format: double, minimum: -180, maximum: 180}
example: -122.4112
- name: phone
in: query
description: Phone number of the business.
schema: {type: string, minLength: 1, maxLength: 32}
example: '+14159083801'
- name: yelp_business_id
in: query
description: A Yelp business id hint to improve match accuracy.
schema: {type: string, minLength: 22, maxLength: 22}
example: example
- name: limit
in: query
description: Number of matches to return.
schema: {type: integer, minimum: 1, maximum: 10, default: 3}
example: 1
- name: match_threshold
in: query
description: How strictly candidates must match the input.
schema:
type: string
enum: [none, default, strict]
default: default
example: none
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
businesses:
type: array
items: {$ref: '#/components/schemas/Business'}
examples:
MatchBusinesses200Example:
summary: Default matchBusinesses 200 response
x-microcks-default: true
value:
businesses:
- id: gR9DTbKCON2g1Z23bWcEpQ
alias: rickys-tacos-san-francisco
name: Ricky's Tacos
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
is_closed: false
url: https://www.yelp.com/biz/rickys-tacos-san-francisco
review_count: 1289
categories:
- alias: rickys-tacos-san-francisco
title: Tacos
parent_aliases: {}
country_whitelist: {}
country_blacklist: {}
rating: 4.5
coordinates:
latitude: 37.7867
longitude: -122.4112
transactions:
- pickup
price: $$
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address:
- example
cross_streets: example
phone: '+14159083801'
display_phone: (415) 908-3801
distance: 1503.4
attributes: {}
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/businesses/{business_id_or_alias}:
get:
tags: [Businesses]
operationId: getBusiness
summary: Get Business Details
description: Returns detailed information about a business by Yelp id or alias.
parameters:
- name: business_id_or_alias
in: path
required: true
description: A 22-character Yelp business id or a business alias.
schema: {type: string}
example: example
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessDetail'
examples:
GetBusiness200Example:
summary: Default getBusiness 200 response
x-microcks-default: true
value:
id: gR9DTbKCON2g1Z23bWcEpQ
alias: rickys-tacos-san-francisco
name: Ricky's Tacos
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
is_closed: false
url: https://www.yelp.com/biz/rickys-tacos-san-francisco
review_count: 1289
categories:
- alias: rickys-tacos-san-francisco
title: Tacos
parent_aliases:
- example
country_whitelist:
- example
country_blacklist:
- example
rating: 4.5
coordinates:
latitude: 37.7867
longitude: -122.4112
transactions:
- pickup
price: $$
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address:
- example
cross_streets: example
phone: '+14159083801'
display_phone: (415) 908-3801
distance: 1503.4
attributes: {}
is_claimed: true
photos:
- example
hours:
- hour_type: REGULAR
open:
- day: 1
start: '1100'
end: '2200'
is_overnight: false
is_open_now: true
special_hours:
- {}
messaging: {}
yelp_menu_url: https://www.yelp.com/menu/rickys-tacos-san-francisco
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/NotFound'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/businesses/{business_id_or_alias}/reviews:
get:
tags: [Reviews]
operationId: getBusinessReviews
summary: Get Business Reviews
description: Returns up to three review excerpts for a business.
parameters:
- name: business_id_or_alias
in: path
required: true
description: A 22-character Yelp business id or a business alias.
schema: {type: string}
example: example
- name: limit
in: query
description: Number of reviews to return.
schema: {type: integer, minimum: 0, maximum: 50, default: 20}
example: 1
- name: offset
in: query
description: Offset into the list of returned reviews.
schema: {type: integer, minimum: 0, maximum: 1000}
example: 1
- name: sort_by
in: query
description: Sort mode for reviews.
schema: {type: string, enum: [yelp_sort], default: yelp_sort}
example: yelp_sort
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ReviewsResponse'
examples:
GetBusinessReviews200Example:
summary: Default getBusinessReviews 200 response
x-microcks-default: true
value:
total: 240
possible_languages:
- example
reviews:
- id: gR9DTbKCON2g1Z23bWcEpQ
url: https://www.yelp.com/biz/rickys-tacos-san-francisco
text: Best tacos in the Bay Area. The al pastor is incredible and the salsa bar is unmatched.
rating: 4.5
time_created: '2026-04-18 19:32:11'
user:
id: gR9DTbKCON2g1Z23bWcEpQ
profile_url: https://www.yelp.com/user_details?userid=abc123
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
name: Ricky's Tacos
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/NotFound'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/autocomplete:
get:
tags: [Businesses]
operationId: autocomplete
summary: Autocomplete
description: Returns autocomplete suggestions for search terms, businesses, and categories.
parameters:
- name: text
in: query
required: true
description: Text to return autocomplete suggestions for.
schema: {type: string, minLength: 1}
example: Best tacos in the Bay Area. The al pastor is incredible and the salsa bar is unmatched.
- name: latitude
in: query
description: Latitude of the location to look for suggestions in.
schema: {type: number, format: double, minimum: -90, maximum: 90}
example: 37.7867
- name: longitude
in: query
description: Longitude of the location to look for suggestions in.
schema: {type: number, format: double, minimum: -180, maximum: 180}
example: -122.4112
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/AutocompleteResponse'
examples:
Autocomplete200Example:
summary: Default autocomplete 200 response
x-microcks-default: true
value:
terms:
- text: Best tacos in the Bay Area. The al pastor is incredible and the salsa bar is unmatched.
businesses:
- id: gR9DTbKCON2g1Z23bWcEpQ
name: Ricky's Tacos
categories:
- alias: rickys-tacos-san-francisco
title: Tacos
parent_aliases:
- example
country_whitelist:
- example
country_blacklist:
- example
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/categories:
get:
tags: [Categories]
operationId: getAllCategories
summary: Get All Categories
description: Returns the full list of Yelp business categories.
parameters:
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
categories:
type: array
items: {$ref: '#/components/schemas/Category'}
examples:
GetAllCategories200Example:
summary: Default getAllCategories 200 response
x-microcks-default: true
value:
categories:
- alias: rickys-tacos-san-francisco
title: Tacos
parent_aliases:
- example
country_whitelist:
- example
country_blacklist:
- example
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/categories/{alias}:
get:
tags: [Categories]
operationId: getCategory
summary: Get Category Details
description: Returns details for a single Yelp category by alias.
parameters:
- name: alias
in: path
required: true
description: The category alias, e.g. "restaurants".
schema: {type: string}
example: rickys-tacos-san-francisco
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
category: {$ref: '#/components/schemas/Category'}
examples:
GetCategory200Example:
summary: Default getCategory 200 response
x-microcks-default: true
value:
category:
alias: rickys-tacos-san-francisco
title: Tacos
parent_aliases:
- example
country_whitelist:
- example
country_blacklist:
- example
'401': {$ref: '#/components/responses/Unauthorized'}
'404': {$ref: '#/components/responses/NotFound'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/events:
get:
tags: [Events]
operationId: searchEvents
summary: Search Events
description: Returns events based on the provided search criteria.
parameters:
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
- name: offset
in: query
description: Offset into the list of returned events.
schema: {type: integer, minimum: 0, maximum: 1000}
example: 1
- name: limit
in: query
description: Number of events to return.
schema: {type: integer, minimum: 0, maximum: 50, default: 3}
example: 1
- name: sort_by
in: query
description: Sort direction.
schema: {type: string, enum: [asc, desc], default: desc}
example: asc
- name: sort_on
in: query
description: Field to sort events on.
schema: {type: string, enum: [popularity, time_start], default: popularity}
example: popularity
- name: start_date
in: query
description: Unix timestamp lower bound for event start time.
schema: {type: integer}
example: 1
- name: end_date
in: query
description: Unix timestamp upper bound for event start time.
schema: {type: integer}
example: 1
- name: categories
in: query
description: Comma-delimited list of event category aliases.
schema: {type: string}
example: example
- name: is_free
in: query
description: Filter for free events.
schema: {type: boolean}
example: true
- name: location
in: query
description: Geographic area to search for events.
schema: {type: string, minLength: 1, maxLength: 250}
example: example
- name: latitude
in: query
description: Latitude of the search center.
schema: {type: number, format: double, minimum: -90, maximum: 90}
example: 37.7867
- name: longitude
in: query
description: Longitude of the search center.
schema: {type: number, format: double, minimum: -180, maximum: 180}
example: -122.4112
- name: radius
in: query
description: Search radius in meters. Maximum 40000.
schema: {type: integer, minimum: 0, maximum: 40000}
example: 1
- name: excluded_events
in: query
description: Comma-delimited list of event ids to exclude.
schema: {type: string}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/EventSearchResponse'
examples:
SearchEvents200Example:
summary: Default searchEvents 200 response
x-microcks-default: true
value:
total: 240
events:
- id: gR9DTbKCON2g1Z23bWcEpQ
name: Ricky's Tacos
category: music
description: Live music in the heart of the Mission District.
time_start: '2026-07-04T19:00:00-07:00'
time_end: '2026-07-04T23:00:00-07:00'
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address: {}
cross_streets: example
latitude: 37.7867
longitude: -122.4112
image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
event_site_url: https://www.yelp.com/events/san-francisco-summer-music-festival
is_free: true
is_canceled: false
is_official: true
attending_count: 312
interested_count: 1024
cost: 0
cost_max: 0
tickets_url: https://www.yelp.com/events/tickets/abc123
business_id: gR9DTbKCON2g1Z23bWcEpQ
'400': {$ref: '#/components/responses/BadRequest'}
'401': {$ref: '#/components/responses/Unauthorized'}
'429': {$ref: '#/components/responses/TooManyRequests'}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v3/events/{event_id}:
get:
tags: [Events]
operationId: getEvent
summary: Get Event Details
description: Returns details for a single event by id.
parameters:
- name: event_id
in: path
required: true
description: The id of the event to retrieve.
schema: {type: string}
example: example
- name: locale
in: query
description: Locale in the form {language}_{country}, e.g. en_US.
schema: {type: string, pattern: "^[a-z]{2,3}_[A-Z]{2}$"}
example: example
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
examples:
GetEvent200Example:
summary: Default getEvent 200 response
x-microcks-default: true
value:
id: gR9DTbKCON2g1Z23bWcEpQ
name: Ricky's Tacos
category: music
description: Live music in the heart of the Mission District.
time_start: '2026-07-04T19:00:00-07:00'
time_end: '2026-07-04T23:00:00-07:00'
location:
address1: 350 Mission St
address2: ''
address3: ''
city: San Francisco
state: CA
zip_code: '94105'
country: US
display_address:
- example
cross_streets: example
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yelp/refs/heads/main/openapi/yelp-openapi.yml