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 to en_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 to ReviewsEndpoint.

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 to en_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 or strict.

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 and ReviewsEndpoint.

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 Yelp

request_a_quote - businesses which actively reply to Request a Quote inquiries

reservation - businesses with Yelp Reservations bookings enabled on their profile page

waitlist_reservation - businesses with Yelp Waitlist bookings enabled on their profile screen (iOS/Android)

deals - businesses offering Yelp Deals on their profile page

gender_neutral_restrooms - businesses which provide gender neutral restrooms

open_to_all - businesses which are Open To All

wheelchair_accessible - businesses which are Wheelchair Accessible

You 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 attributes hot_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 example discgolf, not Disc 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 to en_US.

location: Optional[ConstrainedStrValue]

Required if either latitude or longitude 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 and open_now cannot be used together.

open_now: Optional[bool]

Optional. Default to false. When set to true, only return the businesses open now. Notice that open_at and open_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 or distance. The default is best_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 or restaurants. The term may also be business names, such as Starbucks. 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 to en_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 to en_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 and longitude 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.

categories: List[Category]

A list of category autocomplete suggestions based on the input text.

terms: List[Term]

A list of term 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.

categories: List[Category]

A list of category title and alias pairs associated with this business.

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, and restaurant_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.

categories: List[Category]

A list of category title and alias pairs associated with this business.

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.

hours: Optional[List[Hours]]

Opening hours of the business.

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, and restaurant_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

location: Location

Street, city, state, country, etc. Same as the location in search.

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.

businesses: List[Business]

List of business Yelp finds based on the search criteria.

region: Region

Suggested area in a map to display results in.

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.

businesses: List[Business]

A list of business Yelp finds based on the search criteria.

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.

user: User

The user who wrote the 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.

reviews: List[Review]

A list of up to three reviews of this business.

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.

businesses: List[Business]

A list of business Yelp finds based on the search criteria.

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.

get() Event

Performs a GET request to the endpoint with the configured query parameters. :return:

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 to en_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 is 50.

locale: Optional[str]

Optional. Specify the locale to return the event information in. See SupportedLocales. Defaults to en_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 is 40000 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 order

asc - 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.

get() Event

Performs a GET request to the endpoint with the configured query parameters. :return:

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 to en_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.

events: List[Event]

List of events found matching search criteria.

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 to en_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.

categories: List[Category]

A list of all the categories for this 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.

class yelpfusion3.category.model.CategoryDetails(*, category: Category)

Detailed information about the Yelp category.

category: Category

Detailed information about the Yelp 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

Categories

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

AutocompleteEndpoint

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

BusinessDetailsEndpoint

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

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 either latitude or longitude 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

BusinessSearchEndpoint

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

CategoryDetailsEndpoint

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

EventLookupEndpoint

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

EventSearchEndpoint

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

FeaturedEventEndpoint

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

PhoneSearchEndpoint

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

ReviewsEndpoint

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 either latitude or longitude 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

TransactionSearchEndpoint

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

class yelpfusion3.endpoint.SupportedLocales

A collection of locales supported by the Yelp Fusion API.

static codes() List[str]

Returns a list of all supported locale codes.

Returns

A list containing just the supported locale codes.

Return type

List[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.