Business Endpoints
Endpoints
Abstractions for Yelp Fusion business endpoints.
- class yelpfusion3.business.endpoint.AutocompleteEndpoint(*, text: ConstrainedStrValue, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, locale: Optional[str] = None)
This endpoint returns autocomplete suggestions for search keywords, businesses and categories, based on the input text.
- get() Autocomplete
Performs a GET request to the endpoint with the configured query parameters. :return:
- latitude: Optional[ConstrainedFloatValue]
Required if want to get autocomplete suggestions for businesses. Latitude of the location to look for business autocomplete suggestions.
- locale: Optional[str]
Optional. Specify the locale to return the autocomplete suggestions in. See
SupportedLocales
. Defaults toen_US
.
- longitude: Optional[ConstrainedFloatValue]
Required if want to get autocomplete suggestions for businesses. Longitude of the location to look for business autocomplete suggestions.
- text: ConstrainedStrValue
Required. Text to return autocomplete suggestions for.
- class yelpfusion3.business.endpoint.BusinessDetailsEndpoint(*, business_id: ConstrainedStrValue, locale: Optional[str] = None)
This endpoint returns detailed business content. Normally, you would get the Business ID from
BusinessSearchEndpoint
,ReviewsEndpoint
,TransactionSearchEndpoint
or/autocomplete
. To retrieve review excerpts for a business, please refer toReviewsEndpoint
.Note: at this time, the API does not return businesses without any reviews.
- business_id: ConstrainedStrValue
Unique Yelp ID of the business to query for.
- get() BusinessDetails
Performs a GET request to the endpoint with the configured query parameters. :return:
- locale: Optional[str]
Optional. Specify the locale into which to localize the business information. See
SupportedLocales
. Defaults toen_US
.
- property url: str
Constructs a URL to the business search endpoint with the given query parameters.
- Returns
Yelp Fusion API 3 endpoint URL.
- Return type
str
- class yelpfusion3.business.endpoint.BusinessMatchesEndpoint(*, name: ConstrainedStrValue, address1: ConstrainedStrValue, address2: Optional[ConstrainedStrValue] = None, address3: Optional[ConstrainedStrValue] = None, city: ConstrainedStrValue, state: ConstrainedStrValue, country: ConstrainedStrValue, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, phone: Optional[ConstrainedStrValue] = None, zip_code: Optional[str] = None, yelp_business_id: Optional[str] = None, limit: Optional[ConstrainedIntValue] = None, match_threshold: Optional[Literal['none', 'default', 'strict']] = None)
This endpoint lets you match business data from other sources against businesses on Yelp, based on provided business information. For example, if you know a business’s exact address and name, and you want to find that business and only that business on Yelp.
Note: at this time, the API does not return businesses without any reviews.
- address1: ConstrainedStrValue
Required. The first line of the business’s address. Maximum length is 64; only digits, letters, spaces, and
'/#&,.:
are allowed. The empty string “” is allowed; this will specifically match certain service businesses that have no street address.
- address2: Optional[ConstrainedStrValue]
Optional. The second line of the business’s address. Maximum length is 64; only digits, letters, spaces, and
'/#&,.:
are allowed.
- address3: Optional[ConstrainedStrValue]
Optional. The third line of the business’s address. Maximum length is 64; only digits, letters, spaces, and
'/#&,.:
are allowed.
- classmethod check_country(value: str) str
Checks that “value” is a valid ISO 3166- alpha-2 country code.
- Parameters
value (str) – Two-letter country code.
- Raises
ValueError – If “value” is an invalid country code.
- Returns
“value” if it passes validation.
- Return type
str
- city: ConstrainedStrValue
Required. The city of the business. Maximum length is 64; only digits, letters, spaces, and
'.()
are allowed.
- country: ConstrainedStrValue
Required. The ISO 3166-1 alpha-2 country code of this business. Maximum length is 2.
- get() BusinessMatches
Performs a GET request to the endpoint with the configured query parameters. :return:
- latitude: Optional[ConstrainedFloatValue]
Optional. The WGS84 latitude of the business in decimal degrees. Must be between -90 and +90.
- limit: Optional[ConstrainedIntValue]
Optional. Maximum number of business results to return. By default, it will return 3. Minimum is 1, maximum is 10.
- longitude: Optional[ConstrainedFloatValue]
Optional. The WGS84 longitude of the business in decimal degrees. Must be between -180 and +180.
- match_threshold: Optional[Literal['none', 'default', 'strict']]
Optional. Specifies whether a match quality threshold should be applied to the matched businesses. Must be one of
none
,default
orstrict
.none
: Do not apply any match quality threshold; all potential business matches will be returned.default
: Apply a match quality threshold such that only very closely matching businesses will be returned.strict
: Apply a very strict match quality threshold.
- name: ConstrainedStrValue
Required. The name of the business. Maximum length is 64; only digits, letters, spaces, and
!#$%&+,./:?@'
are allowed.
- phone: Optional[ConstrainedStrValue]
Optional. The phone number of the business which can be submitted as (a) locally formatted with digits only (e.g., 016703080) or (b) internationally formatted with a leading + sign and digits only after (+35316703080). Maximum length is 32.
- state: ConstrainedStrValue
Required. The ISO 3166-2 (with a few exceptions) state code of this business. Maximum length is 3.
- yelp_business_id: Optional[str]
Optional. Unique Yelp identifier of the business if available. Used as a hint when finding a matching business.
- zip_code: Optional[str]
Optional. The Zip code of this business.
- class yelpfusion3.business.endpoint.BusinessSearchEndpoint(*, term: Optional[ConstrainedStrValue] = None, location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, radius: Optional[ConstrainedIntValue] = None, categories: Optional[str] = None, locale: Optional[str] = None, limit: Optional[ConstrainedIntValue] = None, offset: Optional[ConstrainedIntValue] = None, sort_by: Optional[Literal['best_match', 'rating', 'review_count', 'distance']] = None, price: Optional[str] = None, open_now: Optional[bool] = None, open_at: Optional[ConstrainedIntValue] = None, attributes: Optional[str] = None)
This endpoint returns up to 1000 businesses based on the provided search criteria. It has some basic information about the business. To get detailed information and reviews, please use the Business ID returned here and refer to
BusinessDetailsEndpoint
andReviewsEndpoint
.Note: at this time, the API does not return businesses without any reviews.
- attributes: Optional[str]
Optional. Try these additional filters to return specific search results!
hot_and_new
- popular businesses which recently joined Yelprequest_a_quote
- businesses which actively reply to Request a Quote inquiriesreservation
- businesses with Yelp Reservations bookings enabled on their profile pagewaitlist_reservation
- businesses with Yelp Waitlist bookings enabled on their profile screen (iOS/Android)deals
- businesses offering Yelp Deals on their profile pagegender_neutral_restrooms
- businesses which provide gender neutral restroomsopen_to_all
- businesses which are Open To Allwheelchair_accessible
- businesses which are Wheelchair AccessibleYou can combine multiple attributes by providing a comma separated like
attribute1,attribute2
. If multiple attributes are used, only businesses that satisfy ALL attributes will be returned in search results. For example, the attributeshot_and_new,request_a_quote
will return businesses that are Hot and New AND offer Request a Quote.
- categories: Optional[str]
Optional. Categories to filter the search results with. See the list of supported categories. The category filter can be a list of comma delimited categories. For example,
bars,french
will filter by Bars OR French. The category identifier should be used (for examplediscgolf
, notDisc Golf
).
- get() BusinessSearch
Performs a GET request to the endpoint with the configured query parameters. :return:
- latitude: Optional[ConstrainedFloatValue]
Required if
location
is not provided. Latitude of the location you want to search nearby.
- limit: Optional[ConstrainedIntValue]
Optional. Number of business results to return. By default, it will return 20. Maximum is 50.
- locale: Optional[str]
Optional. Specify the locale into which to localize the business information. See
SupportedLocales
. Defaults toen_US
.
- location: Optional[ConstrainedStrValue]
Required if either
latitude
orlongitude
is not provided. This string indicates the geographic area to be used when searching for businesses. Examples:New York City
,NYC
,350 5th Ave, New York, NY 10118
. Businesses returned in the response may not be strictly within the specified location.
- longitude: Optional[ConstrainedFloatValue]
Required if
location
is not provided. Longitude of the location you want to search nearby.
- offset: Optional[ConstrainedIntValue]
Optional. Offset the list of returned business results by this amount.
- open_at: Optional[ConstrainedIntValue]
Optional. An integer representing the Unix time in the same timezone of the search location. If specified, it will return business open at the given time. Notice that
open_at
andopen_now
cannot be used together.
- open_now: Optional[bool]
Optional. Default to
false
. When set to true, only return the businesses open now. Notice thatopen_at
andopen_now
cannot be used together.
- price: Optional[str]
Optional. Pricing levels to filter the search result with: 1 = $, 2 = $$, 3 = $$$, 4 = $$$$. The price filter can be a list of comma delimited pricing levels. For example,
1, 2, 3
will filter the results to show the ones that are $, $$, or $$$.
- radius: Optional[ConstrainedIntValue]
Optional. A suggested search radius in meters. This field is used as a suggestion to the search. The actual search radius may be lower than the suggested radius in dense urban areas, and higher in regions of less business density. If the specified value is too large, a AREA_TOO_LARGE error may be returned. The max value is 40000 meters (about 25 miles).
- sort_by: Optional[Literal['best_match', 'rating', 'review_count', 'distance']]
Optional. Suggestion to the search algorithm that the results be sorted by one of the these modes:
best_match
,rating
,review_count
ordistance
. The default isbest_match
. Note that specifying the sort_by is a suggestion (not strictly enforced) to Yelp’s search, which considers multiple input parameters to return the most relevant results. For example, the rating sort is not strictly sorted by the rating value, but by an adjusted rating value that takes into account the number of ratings, similar to a Bayesian average. This is to prevent skewing results to businesses with a single review.
- term: Optional[ConstrainedStrValue]
Optional. Search term, for example
food
orrestaurants
. The term may also be business names, such asStarbucks
. If term is not included the endpoint will default to searching across businesses from a small number of popular categories.
- class yelpfusion3.business.endpoint.PhoneSearchEndpoint(*, phone: ConstrainedStrValue, locale: Optional[str] = None)
This endpoint returns a list of businesses based on the provided phone number. It is possible for more than one business to have the same phone number (for example, chain stores with the same +1 800 phone number).
Note: at this time, the API does not return businesses without any reviews.
- get() PhoneSearch
Performs a GET request to the endpoint with the configured query parameters. :return:
- locale: Optional[str]
Optional. Specify the locale into which to localize the business information. See
SupportedLocales
. Defaults toen_US
.
- phone: ConstrainedStrValue
Required. Phone number of the business you want to search for. It must start with + and include the country code, like
+14159083801
.
- class yelpfusion3.business.endpoint.ReviewsEndpoint(*, business_id: ConstrainedStrValue, locale: Optional[str] = None)
This endpoint returns up to three review excerpts for a given business ordered by Yelp’s default sort order.
Note: at this time, the API does not return businesses without any reviews.
- business_id: ConstrainedStrValue
Unique Yelp ID of the business to query for.
- get() Reviews
Performs a GET request to the endpoint with the configured query parameters. :return:
- locale: Optional[str]
Optional. Specify the locale into which to localize the business information. See
SupportedLocales
. Defaults toen_US
.
- property url: str
Constructs a URL to the reviews endpoint with the given query parameters.
- Returns
Yelp Fusion API 3 endpoint URL.
- Return type
str
- class yelpfusion3.business.endpoint.TransactionSearchEndpoint(*, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, location: Optional[ConstrainedStrValue] = None)
This endpoint returns a list of businesses which support food delivery transactions.
Note: at this time, the API does not return businesses without any reviews.
- get() TransactionSearch
Performs a GET request to the endpoint with the configured query parameters. :return:
- latitude: Optional[ConstrainedFloatValue]
Required when
location
isn’t provided. Latitude of the location you want to deliver to.
- location: Optional[ConstrainedStrValue]
Required when
latitude
andlongitude
aren’t provided. Address of the location you want to deliver to.
- longitude: Optional[ConstrainedFloatValue]
Required when
location
isn’t provided. Longitude of the location you want to deliver to.
Models
Model abstractions for Yelp Fusion business endpoints.
- class yelpfusion3.business.model.Autocomplete(*, terms: List[Term], businesses: List[BusinessSuggestion], categories: List[Category])
Autocomplete suggestions based on input text.
- businesses: List[BusinessSuggestion]
A list of business autocomplete suggestions based on the input text.
- class yelpfusion3.business.model.Business(*, categories: List[Category], coordinates: Optional[Coordinates] = None, display_phone: str, distance: Optional[float] = None, id: ConstrainedStrValue, alias: str, image_url: Optional[HttpUrl] = None, is_closed: bool, location: Location, name: str, phone: Optional[str] = None, price: Optional[Literal['$', '$$', '$$$', '$$$$']] = None, rating: ConstrainedFloatValue, review_count: NonNegativeInt, url: HttpUrl, transactions: List[Literal['pickup', 'delivery', 'restaurant_reservation']])
Details for a business found with a business search.
- alias: str
Unique Yelp alias of this business. Can contain unicode characters. Example:
yelp-san-francisco
.
- coordinates: Optional[Coordinates]
The coordinates of this business.
- display_phone: str
Phone number of the business formatted nicely to be displayed to users. The format is the standard phone number format for the business’s country.
- distance: Optional[float]
Distance in meters from the search location. This returns meters regardless of the locale.
- id: ConstrainedStrValue
Unique Yelp ID of this business. Example:
4kMBvIEWPxWkWKFN__8SxQ
- image_url: Optional[HttpUrl]
URL of photo for this business.
- is_closed: bool
Whether business has been (permanently) closed
- location: Location
The location of this business, including address, city, state, zip code and country.
- name: str
Name of this business.
- phone: Optional[str]
Phone number of the business.
- price: Optional[Literal['$', '$$', '$$$', '$$$$']]
Price level of the business. Value is one of
$
,$$
,$$$
and$$$$
.
- rating: ConstrainedFloatValue
Rating for this business (value ranges from 1, 1.5, … 4.5, 5).
- review_count: NonNegativeInt
Number of reviews for this business.
- transactions: List[Literal['pickup', 'delivery', 'restaurant_reservation']]
A list of Yelp transactions that the business is registered for. Current supported values are
pickup
,delivery
, andrestaurant_reservation
.
- url: HttpUrl
URL for business page on Yelp.
- class yelpfusion3.business.model.BusinessDetails(*, id: ConstrainedStrValue, alias: str, name: str, image_url: Optional[HttpUrl] = None, is_claimed: bool, is_closed: bool, url: HttpUrl, phone: str, display_phone: str, review_count: NonNegativeInt, categories: List[Category], rating: ConstrainedFloatValue, location: Location, coordinates: Optional[Coordinates] = None, photos: Optional[List[HttpUrl]] = None, price: Literal['$', '$$', '$$$', '$$$$'], hours: Optional[List[Hours]] = None, transactions: List[Literal['pickup', 'delivery', 'restaurant_reservation']], special_hours: Optional[List[SpecialHours]] = None)
Detailed information about a business.
- alias: str
Unique Yelp alias of this business. Can contain unicode characters. Example:
yelp-san-francisco
.
- coordinates: Optional[Coordinates]
The coordinates of this business.
- display_phone: str
Phone number of the business formatted nicely to be displayed to users. The format is the standard phone number format for the business’s country.
- id: ConstrainedStrValue
Unique Yelp ID of this business. Example:
4kMBvIEWPxWkWKFN__8SxQ
- image_url: Optional[HttpUrl]
URL of photo for this business.
- is_claimed: bool
Whether business has been claimed by a business owner.
- is_closed: bool
Whether business has been (permanently) closed.
- location: Location
The location of this business, including address, city, state, zip code and country.
- name: str
Name of this business.
- phone: str
Phone number of the business.
- photos: Optional[List[HttpUrl]]
URLs of up to three photos of the business.
- price: Literal['$', '$$', '$$$', '$$$$']
Price level of the business. Value is one of
$
,$$
,$$$
and$$$$
.
- rating: ConstrainedFloatValue
Rating for this business (value ranges from 1, 1.5, … 4.5, 5).
- review_count: NonNegativeInt
Number of reviews for this business.
- special_hours: Optional[List[SpecialHours]]
Out of the ordinary hours for the business that apply on certain dates. Whenever these are set, they will override the regular business hours found in the
hours
field.
- transactions: List[Literal['pickup', 'delivery', 'restaurant_reservation']]
A list of Yelp transactions that the business is registered for. Current supported values are
pickup
,delivery
, andrestaurant_reservation
.
- url: HttpUrl
URL for business page on Yelp.
- class yelpfusion3.business.model.BusinessMatch(*, id: ConstrainedStrValue, alias: str, name: str, location: Location, coordinates: Optional[Coordinates] = None, phone: str)
A Yelp business matching the inputs.
- alias: str
Unique Yelp alias of this business. Can contain unicode characters.
- coordinates: Optional[Coordinates]
Latitude and longitude, if available. Same as the
coordinates
in search.
- id: ConstrainedStrValue
Unique Yelp ID of this business. Example:
4kMBvIEWPxWkWKFN__8SxQ
- name: str
Name of this business.
- phone: str
The business’s phone number.
- class yelpfusion3.business.model.BusinessMatches(*, businesses: List[BusinessMatch])
List of Yelp business matches.
- businesses: List[BusinessMatch]
List of Yelp business matches.
- class yelpfusion3.business.model.BusinessSearch(*, total: int, businesses: List[Business], region: Region)
A list of businesses based on a location search.
- total: int
Total number of business Yelp finds based on the search criteria. Sometimes, the value may exceed 1000. In such case, you still can only get up to 1000 businesses using multiple queries and combinations of the “limit” and “offset” parameters.
- class yelpfusion3.business.model.BusinessSuggestion(*, name: ConstrainedStrValue, id: ConstrainedStrValue)
An autocomplete suggestion for a business.
- id: ConstrainedStrValue
Yelp ID of the business.
- name: ConstrainedStrValue
Name of the business.
- class yelpfusion3.business.model.Category(*, alias: str, title: str)
Category title and alias pairs associated with this business.
- alias: str
Alias of a category, when searching for business in certain categories, use alias rather than the title.
- title: str
Title of a category for display purpose.
- class yelpfusion3.business.model.Coordinates(*, latitude: ConstrainedFloatValue, longitude: ConstrainedFloatValue)
The coordinates of this business.
- latitude: ConstrainedFloatValue
The latitude of this business.
- longitude: ConstrainedFloatValue
The longitude of this business.
- class yelpfusion3.business.model.DetailedHours(*, is_overnight: bool = False, start: str, end: str, day: Literal[0, 1, 2, 3, 4, 5, 6])
Opening hours of the business for a given day of the week.
- day: Literal[0, 1, 2, 3, 4, 5, 6]
From 0 to 6, representing day of the week from Monday to Sunday. Notice that you may get the same day of the week more than once if the business has more than one opening time slots.
- end: str
End of the opening hours in a day, in 24-hour clock notation, like
2130
means 9:30 PM.
- is_overnight: bool
Whether the business opens overnight or not. When this is
True
, the end time will be lower than the start time.
- start: str
Start of the opening hours in a day, in 24-hour clock notation, like
1000
means 10 AM.
- class yelpfusion3.business.model.Hours(*, open: List[DetailedHours] = [], hours_type: Literal['REGULAR'], is_open_now: bool)
Opening hours of the business.
- hours_type: Literal['REGULAR']
The type of the opening hours information. Right now, this is always
REGULAR
.
- is_open_now: bool
Whether the business is currently open or not.
- open: List[DetailedHours]
Opening hours of the business.
- class yelpfusion3.business.model.PhoneSearch(*, total: NonNegativeInt, businesses: List[Business])
A list of businesses based on the provided phone number.
- total: NonNegativeInt
The total number of business Yelp finds based on the search criteria. Sometimes, the value may exceed 1000. In such case, you still can only get up to 1000 businesses.
- class yelpfusion3.business.model.Region(*, center: Coordinates)
Suggested area in a map to display results in.
- center: Coordinates
Center position of map area.
- class yelpfusion3.business.model.Review(*, id: ConstrainedStrValue, text: str, url: HttpUrl, rating: Literal[1, 2, 3, 4, 5], time_created: datetime, user: User)
A review excerpt for a given business.
- id: ConstrainedStrValue
A unique identifier for this review.
- rating: Literal[1, 2, 3, 4, 5]
Rating of this review.
- text: str
Text excerpt of this review.
- time_created: datetime
The time that the review was created in PST.
- url: HttpUrl
URL of this review.
- class yelpfusion3.business.model.Reviews(*, total: NonNegativeInt, possible_languages: List[str], reviews: List[Review])
Review excerpts for a given business.
- possible_languages: List[str]
A list of languages for which the business has at least one review.
- total: NonNegativeInt
The total number of reviews that the business has.
- class yelpfusion3.business.model.SpecialHours(*, date: str, is_closed: Optional[bool] = None, start: str, end: str, is_overnight: bool)
Out of the ordinary hours for the business that apply on certain dates. Whenever these are set, they will override the regular business hours found in the
hours
field.- date: str
An ISO8601 date string representing the date for which these special hours apply.
- end: str
End of the opening hours in a day, in 24-hour clock notation, like
2130
means 9:30 PM.
- is_closed: Optional[bool]
Whether this particular special hour represents a date where the business is closed.
- is_overnight: bool
Whether the special hours time range spans across midnight or not. When this is
True
, the end time will be lower than the start time.
- start: str
Start of the opening hours in a day, in 24-hour clock notation, like
1000
means 10 AM.
- class yelpfusion3.business.model.Term(*, text: ConstrainedStrValue)
A term autocomplete suggestion.
- text: ConstrainedStrValue
The text content of the term autocomplete suggestion.
- class yelpfusion3.business.model.TransactionSearch(*, total: NonNegativeInt, businesses: List[Business])
A list of businesses which support food delivery transactions.
- total: NonNegativeInt
The total number of business Yelp finds based on the search criteria. Sometimes, the value may exceed 1000. In such case, you still can only get up to 1000 businesses.
- class yelpfusion3.business.model.User(*, id: ConstrainedStrValue, profile_url: HttpUrl, name: ConstrainedStrValue, image_url: Optional[HttpUrl] = None)
A user who wrote a review.
- id: ConstrainedStrValue
ID of the user.
- image_url: Optional[HttpUrl]
URL of the user’s profile photo.
- name: ConstrainedStrValue
User screen name (first name and first initial of last name).
- profile_url: HttpUrl
URL of the user’s profile.
Event Endpoints
Important
The Event endpoints are only through the Yelp Developer Beta program.
Sign up for the Yelp Developer Beta program on the Manage App page and click the Join button.
Endpoints
Abstractions for Yelp Fusion event endpoints.
- class yelpfusion3.event.endpoint.EventLookupEndpoint(*, id: str, locale: Optional[str] = None)
This endpoint returns the detailed information of a Yelp event.
- id: str
ID of the Yelp event to query for.
- locale: Optional[str]
Optional. Specify the locale to return the event information in. See
SupportedLocales
. Defaults toen_US
.
- property url: str
Constructs a URL to the event lookup endpoint with the given query parameters.
- Returns
Yelp Fusion API 3 endpoint URL.
- Return type
str
- class yelpfusion3.event.endpoint.EventSearchEndpoint(*, locale: Optional[str] = None, offset: Optional[int] = None, limit: Optional[ConstrainedIntValue] = None, sort_by: Optional[Literal['desc', 'asc']] = None, sort_on: Optional[Literal['popularity', 'time_start']] = None, start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, categories: Optional[ConstrainedStrValue] = None, is_free: Optional[bool] = None, location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, radius: Optional[ConstrainedIntValue] = None, excluded_events: Optional[ConstrainedStrValue] = None)
This endpoint returns events based on the provided search criteria.
- categories: Optional[ConstrainedStrValue]
Optional. The category filter can be a list of comma delimited categories to get OR’d results that include the categories provided. See
SupportedCategories
.
- end_date: Optional[datetime]
Optional. Unix timestamp. Will return events that only end at or before the specified time. Value must be in the range
-2208960000
<=end_date
<=221845420800
.
- excluded_events: Optional[ConstrainedStrValue]
Optional. List of event ids. Events associated with these event ids in this list will not show up in the response.
- get() EventSearch
Performs a GET request to the endpoint with the configured query parameters. :return:
- is_free: Optional[bool]
Optional. Filter whether the events are free to attend. By default no filter is applied so both free and paid events will be returned.
- latitude: Optional[ConstrainedFloatValue]
Optional. Latitude of the location you want to search nearby. If latitude is provided, longitude is required too.
- limit: Optional[ConstrainedIntValue]
Optional. Number of events results to return. By default, it will return
3
. Maximum is50
.
- locale: Optional[str]
Optional. Specify the locale to return the event information in. See
SupportedLocales
. Defaults toen_US
.
- location: Optional[ConstrainedStrValue]
Optional. Specifies the combination of “address, neighborhood, city, state or zip, optional country” to be used when searching for events.
- longitude: Optional[ConstrainedFloatValue]
Optional. Longitude of the location you want to search nearby. If longitude is provided, latitude is required too.
- offset: Optional[int]
Optional. Offset the list of returned events by this amount.
- radius: Optional[ConstrainedIntValue]
Optional. Search radius in meters. If the value is too large, a
AREA_TOO_LARGE
error may be returned. The max value is40000
meters (about 25 miles).
- sort_by: Optional[Literal['desc', 'asc']]
Optional. Sort by either descending or ascending order. By default, it returns results in descending order. Possible values are:
desc
- sort by descending orderasc
- sort by ascending order
- sort_on: Optional[Literal['popularity', 'time_start']]
Optional. Sort on popularity or time start. By default, sorts on
popularity
. Possible values are:popularity
time_start
- start_date: Optional[datetime]
Optional. Unix timestamp. Will return events that only begin at or after the specified time. Value must be in the range
-2208960000
<=start_date
<=221845420800
.
- class yelpfusion3.event.endpoint.FeaturedEventEndpoint(*, locale: Optional[str] = None, location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None)
This endpoint returns the featured event for a given location. Featured events are chosen by Yelp’s community managers.
- latitude: Optional[ConstrainedFloatValue]
Required, if location not provided. Latitude of the location to search from.
- locale: Optional[str]
Optional. Specify the locale to return the event information in. See
SupportedLocales
. Defaults toen_US
.
- location: Optional[ConstrainedStrValue]
Required, if latitude and longitude not provided. Specifies the combination of “address, neighborhood, city, state or zip, optional country” to be used while searching for events.
- longitude: Optional[ConstrainedFloatValue]
Required, if location not provided. Longitude of the location to search from.
Models
Model abstractions for Yelp Fusion event endpoints.
- class yelpfusion3.event.model.Event(*, attending_count: Optional[NonNegativeInt] = None, category: Optional[str] = None, cost: Optional[ConstrainedFloatValue] = None, cost_max: Optional[ConstrainedFloatValue] = None, description: Optional[str] = None, event_site_url: Optional[HttpUrl] = None, id: Optional[ConstrainedStrValue] = None, image_url: Optional[HttpUrl] = None, interested_count: Optional[NonNegativeInt] = None, is_canceled: Optional[bool] = None, is_free: Optional[bool] = None, is_official: Optional[bool] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None, name: Optional[ConstrainedStrValue] = None, tickets_url: Optional[Union[HttpUrl, Literal['']]] = None, time_end: Optional[str] = None, time_start: Optional[str] = None, location: Optional[Location] = None, business_id: Optional[ConstrainedStrValue] = None)
Detailed information for a specific Yelp event.
- attending_count: Optional[NonNegativeInt]
Number of Yelp users attending this event.
- business_id: Optional[ConstrainedStrValue]
Yelp Business ID of this event. No ID is returned if a business is not associated with an event.
- category: Optional[str]
The category of this event.
- cost: Optional[ConstrainedFloatValue]
Cost of attending this event.
- cost_max: Optional[ConstrainedFloatValue]
Maximum cost of attending this event.
- description: Optional[str]
Detailed description of this event.
- event_site_url: Optional[HttpUrl]
Yelp page of this event.
- id: Optional[ConstrainedStrValue]
Event id.
- image_url: Optional[HttpUrl]
Yelp image URL of this event.
- interested_count: Optional[NonNegativeInt]
Number of Yelp users interested in attending this event.
- is_canceled: Optional[bool]
Whether this event is canceled.
- is_free: Optional[bool]
Whether this event is free.
- is_official: Optional[bool]
Whether this event is created by a Yelp community manager.
- latitude: Optional[ConstrainedFloatValue]
Latitude of this event.
- location: Optional[Location]
Location object of the event. Includes address, city, state, zip code and country.
- longitude: Optional[ConstrainedFloatValue]
Longitude of this event.
- name: Optional[ConstrainedStrValue]
Name of this event.
- tickets_url: Optional[Union[HttpUrl, Literal['']]]
URL to buy tickets for this event.
- time_end: Optional[str]
Time this event ends. Returns date and time in ISO 8601 format:
YYYY-MM-DDTHH:MM:SS+HH:MM
.
- time_start: Optional[str]
Time this event starts. Returns date and time in ISO 8601 format:
YYYY-MM-DDTHH:MM:SS+HH:MM
.
- class yelpfusion3.event.model.EventSearch(*, total: int, events: List[Event])
Events returned by
EventSearchEndpoint
.- total: int
Total number of events returned based on search criteria.
- class yelpfusion3.event.model.SupportedCategories
A collection of categories supported by the Yelp Fusion API’s Event Search endpoint. See Supported Categories
- static contains(value: ConstrainedStrValue) bool
Checks that
value
is a category supported by the Yelp Fusion API’s Event search endpoint.- Parameters
value (str) – The category alias to check.
- Returns
True if the category alias is supported.
- Return type
bool
Category Endpoints
Important
The Category endpoints are only through the Yelp Developer Beta program.
Sign up for the Yelp Developer Beta program on the Manage App page and click the Join button.
Endpoints
Abstractions for Yelp Fusion category endpoints.
- class yelpfusion3.category.endpoint.AllCategoriesEndpoint(*, locale: Optional[str] = None)
This endpoint returns all Yelp business categories across all locales by default. Include the “locale” parameter to filter to only those categories available for a particular locale, and translate/localize the names of those categories.
- get() Categories
Performs a GET request to the endpoint with the configured query parameters. :return:
- locale: Optional[str]
Optional. Specify the locale to filter the categories returned to only those available in that locale, and to translate the names of the categories appropriately. See
SupportedLocales
. If not included, all categories across all locales will be returned and the category names will be in English.
- class yelpfusion3.category.endpoint.CategoryDetailsEndpoint(*, locale: Optional[str] = None, alias: ConstrainedStrValue)
This endpoint returns detailed information about the Yelp category specified by a Yelp category alias.
- alias: ConstrainedStrValue
Required. Specify the alias of the category.
- get() CategoryDetails
Performs a GET request to the endpoint with the configured query parameters. :return:
- locale: Optional[str]
Optional. Specify the locale to return the autocomplete suggestions in. See
SupportedLocales
. Defaults toen_US
.
- property url: str
Constructs a URL to the category details endpoint with the given query parameters.
- Returns
Yelp Fusion API 3 endpoint URL.
- Return type
str
Models
Model abstractions for Yelp Fusion category endpoints.
- class yelpfusion3.category.model.Categories(*, categories: List[Category])
All Yelp business categories for a given locale.
- class yelpfusion3.category.model.Category(*, alias: ConstrainedStrValue, title: ConstrainedStrValue, parent_aliases: List[ConstrainedStrValue] = [], country_whitelist: List[ConstrainedStrValue] = [], country_blacklist: List[ConstrainedStrValue] = [])
Detailed information about a Yelp category.
- alias: ConstrainedStrValue
Category alias.
- country_blacklist: List[ConstrainedStrValue]
Countries for which this category is blacklisted.
- country_whitelist: List[ConstrainedStrValue]
Countries for which this category is whitelisted.
- parent_aliases: List[ConstrainedStrValue]
List of aliases of parent categories.
- title: ConstrainedStrValue
Title of this category.
Client
A Python client for the Yelp Fusion v3 API.
- class yelpfusion3.client.Client
Client is a collection of factory methods that create
Endpoint
objects used to interact with Yelp Fusion endpoints. Function parameters provide guidance on which endpoint parameters are required. Optional parameters can be added to the instantiated object by setting their respective fields.- static all_categories() AllCategoriesEndpoint
This endpoint returns all Yelp business categories across all locales by default.
- Returns
An endpoint wrapper for the Yelp All Categories REST endpoint.
- Return type
- static autocomplete(text: ConstrainedStrValue, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None) AutocompleteEndpoint
Creates a new
AutocompleteEndpoint
object used to interact with the Yelp Autocomplete REST endpoint.- Parameters
text (str) – Required. Text to return autocomplete suggestions for.
latitude (float) – Required if want to get autocomplete suggestions for businesses. Latitude of the location to look for business autocomplete suggestions.
longitude (float) – Required if want to get autocomplete suggestions for businesses. Longitude of the location to look for business autocomplete suggestions.
- Returns
An endpoint wrapper for the Yelp Autocomplete REST endpoint.
- Return type
- static business_details(business_id: ConstrainedStrValue) BusinessDetailsEndpoint
Creates a new
BusinessDetailsEndpoint
object used to interact with the Yelp Business Details REST endpoint.- Parameters
business_id (str) – Unique Yelp ID of the business to query for.
- Returns
An endpoint wrapper for the Yelp Business Details REST endpoint.
- Return type
- static business_matches(name: ConstrainedStrValue, address1: ConstrainedStrValue, city: ConstrainedStrValue, state: ConstrainedStrValue, country: ConstrainedStrValue) BusinessMatchesEndpoint
Creates a new
BusinessMatchesEndpoint
object used to interact with the Yelp Business Matches REST endpoint.- Parameters
name (str) – The name of the business. Maximum length is 64; only digits, letters, spaces, and
!#$%&+,./:?@'
are allowed.address1 (str) – The first line of the business’s address. Maximum length is 64; only digits, letters, spaces, and
’/#&,.:
are allowed. The empty string “” is allowed; this will specifically match certain service businesses that have no street address.city (str) – The city of the business. Maximum length is 64; only digits, letters, spaces, and
’.()
are allowed.state (str) – The ISO 3166-2 (with a few exceptions) state code of this business.
country (str) – The ISO 3166-1 alpha-2 country code of this business.
- Returns
An endpoint wrapper for the Yelp Business Match REST endpoint.
- Return type
BusinessMatchEndpoint
- static business_search(location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None) BusinessSearchEndpoint
Creates a new
BusinessSearchEndpoint
object used to interact with the Yelp Business Search REST endpoint.- Parameters
location (str) – This string indicates the geographic area to be used when searching for businesses. Examples:
New York City
,NYC
,350 5th Ave, New York, NY 10118
. (Required if eitherlatitude
orlongitude
is not provided.)latitude (float) – Latitude of the location you want to search nearby. (Required if
location
is not provided.)longitude (float) – Longitude of the location you want to search nearby. (Required if
location
is not provided.)
- Returns
An endpoint wrapper for the Yelp Business Search REST endpoint.
- Return type
- static category_details(alias: ConstrainedStrValue) CategoryDetailsEndpoint
Creates a new
CategoryDetailsEndpoint
object used to interact with the Yelp Category Details REST endpoint.- Parameters
alias (str) – The alias of the category.
- Returns
An endpoint wrapper for the Yelp Category Details REST endpoint.
- Return type
- static event_lookup(event_id: str) EventLookupEndpoint
Creates a new
EventLookupEndpoint
object used to interact with the Yelp Event Lookup REST endpoint.- Parameters
event_id (str) – ID of the Yelp event to query for.
- Returns
An endpoint wrapper for the Yelp Event Lookup REST endpoint.
- Return type
- static event_search() EventSearchEndpoint
Creates a new
EventSearchEndpoint
object used to interact with the Yelp Event Search REST endpoint.- Returns
An endpoint wrapper for the Yelp Event Search REST endpoint.
- Return type
- static featured_event(location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None) FeaturedEventEndpoint
Creates a new
FeaturedEventEndpoint
object used to interact with the Yelp Featured Event REST endpoint.- Parameters
location (str) – Required, if latitude and longitude not provided. Specifies the combination of “address, neighborhood, city, state or zip, optional country” to be used while searching for events.
latitude (float) – Required, if location not provided. Latitude of the location to search from.
longitude (float) – Required, if location not provided. Longitude of the location to search from.
- Returns
An endpoint wrapper for the Yelp Featured Event REST endpoint.
- Return type
- static phone_search(phone: ConstrainedStrValue) PhoneSearchEndpoint
Creates a new
PhoneSearchEndpoint
object used to interact with the Yelp Phone Search REST endpoint.- Parameters
phone (str) – Phone number of the business you want to search for. It must start with + and include the country code, like
+14159083801
.- Returns
An endpoint wrapper for the Yelp Phone Search REST endpoint.
- Return type
- static reviews(business_id: ConstrainedStrValue) ReviewsEndpoint
Creates a new
ReviewsEndpoint
object used to interact with the Yelp Reviews REST endpoint.- Parameters
business_id (str) – Unique Yelp ID of the business to query for.
- Returns
An endpoint wrapper for the Yelp Reviews REST endpoint.
- Return type
- static transaction_search(location: Optional[ConstrainedStrValue] = None, latitude: Optional[ConstrainedFloatValue] = None, longitude: Optional[ConstrainedFloatValue] = None) TransactionSearchEndpoint
Creates a new
TransactionSearchEndpoint
object used to interact with the Yelp Transaction Search REST endpoint.- Parameters
location (str) – This string indicates the geographic area to be used when searching for businesses. Examples:
New York City
,NYC
,350 5th Ave, New York, NY 10118
. (Required if eitherlatitude
orlongitude
is not provided.)latitude (float) – Latitude of the location you want to search nearby. (Required if
location
is not provided.)longitude (float) – Longitude of the location you want to search nearby. (Required if
location
is not provided.)
- Returns
An endpoint wrapper for the Yelp Transaction Search REST endpoint.
- Return type
Endpoint
Shared endpoint abstractions used by multiple Yelp Fusion v3 endpoints.
- class yelpfusion3.endpoint.Endpoint
Basic base class for all endpoint implementations.
- abstract get() Model
Performs a GET request to the endpoint with the configured query parameters. :return:
- property url: str
Constructs a URL to the endpoint with the given query parameters.
- Returns
Yelp Fusion API 3 endpoint URL.
- Return type
str
Model
Shared data models used by multiple Yelp Fusion v3 endpoints.
- class yelpfusion3.model.Location(*, address1: Optional[str] = None, address2: Optional[str] = None, address3: Optional[str] = None, city: str, state: ConstrainedStrValue, zip_code: str, country: ConstrainedStrValue, display_address: List[str], cross_streets: Optional[str] = None)
The location of a business or event, including address, city, state, zip code and country.
- address1: Optional[str]
Street address of this business or event.
- address2: Optional[str]
Street address of this business or event, continued.
- address3: Optional[str]
Street address of this business or event, continued.
- city: str
City of this business or event.
- country: ConstrainedStrValue
ISO 3166-1 alpha-2 country code of this business or event.
- cross_streets: Optional[str]
Cross streets for this business or event. (Only used in business or event details search results.)
- display_address: List[str]
Array of strings that if organized vertically give an address that is in the standard address format for the business or event’s country.
- state: ConstrainedStrValue
ISO 3166-2 (with a few exceptions) state code of this business or event.
- zip_code: str
Zip code of this business or event.
- class yelpfusion3.model.Model
Basic base class for all model implementations.