This Swift wrapper covers all possible network endpoints and responses for the Yelp Fusion API.
For a demonstration of the capabilities of CDYelpFusionKit; run the iOS Example project after cloning the repo.
- Features
- Requirements
- Dependencies
- Installation
- Contributing
- Usage
- Initialization
- Search Endpoint
- Phone Search Endpoint
- Transaction Search Endpoint
- Business Endpoint
- Business Match Endpoint
- Reviews Endpoint
- Autocomplete Endpoint
- Event Lookup Endpoint
- Event Search Endpoint
- Featured Event Endpoint
- All Categories Endpoint
- Category Details Endpoint
- Deep Linking
- Web Linking
- Brand Assets
- Author
- Resources
- License
Features
- Authentication
- API Endpoints
- Search
- Phone Search
- Transaction Search
- Business
- Business Match
- Reviews
- Autocomplete
- Event Lookup
- Event Search
- Featured Event
- All Categories
- Category Details
- Deep Linking
- Web Linking
- Brand Assets
- Color
- Logos
- Platform Support
- iOS
- macOS
- tvOS
- watchOS
- Documentation
Requirements
- iOS 10.0+ / macOS 10.12+ / tvOS 10.0+ / watchOS 3.0+
- Swift 5.3+
- Yelp API Access
Dependencies
Installation
CocoaPods
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate CDYelpFusionKit into your Xcode project using CocoaPods, specify it in your Podfile
:
pod 'CDYelpFusionKit', '3.2.0'
Carthage
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To integrate CDYelpFusionKit into your Xcode project using Carthage, specify it in your Cartfile
:
github "chrisdhaan/CDYelpFusionKit" == 3.2.0
Swift Package Manager
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift
compiler.
Once you have your Swift package set up, adding CDYelpFusionKit as a dependency is as easy as adding it to the dependencies
value of your Package.swift
.
dependencies: [
.package(url: "https://github.com/chrisdhaan/CDYelpFusionKit.git", .upToNextMajor(from: "3.2.0"))
]
Git Submodule
If you prefer not to use any of the aforementioned dependency managers, you can integrate CDYelpFusionKit into your project manually.
- Open up Terminal,
cd
into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:
$ git init
- Add CDYelpFusionKit as a git submodule by running the following command:
git submodule add https://github.com/chrisdhaan/CDYelpFusionKit.git
-
Open the new
CDYelpFusionKit
folder, and drag theCDYelpFusionKit.xcodeproj
into the Project Navigator of your application's Xcode project.It should appear nested underneath your application's blue project icon. Whether it is above or below all the other Xcode groups does not matter.
-
Select the
CDYelpFusionKit.xcodeproj
in the Project Navigator and verify the deployment target matches that of your application target. -
Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.
-
In the tab bar at the top of that window, open the "General" panel.
-
Click on the
+
button under the "Embedded Binaries" section. -
You will see two different
CDYelpFusionKit.xcodeproj
folders each with two different versions of theCDYelpFusionKit.framework
nested inside aProducts
folder.It does not matter which
Products
folder you choose from, but it does matter whether you choose the top or bottomCDYelpFusionKit.framework
. -
Select the top
CDYelpFusionKit.framework
for iOS and the bottom one for macOS.You can verify which one you selected by inspecting the build log for your project. The build target for
CDYelpFusionKit
will be listed as eitherCDYelpFusionKit iOS
,CDYelpFusionKit macOS
,CDYelpFusionKit tvOS
orCDYelpFusionKit watchOS
. -
And that's it!
The
CDYelpFusionKit.framework
is automagically added as a target dependency, linked framework and embedded framework in a copy files build phase which is all you need to build on the simulator and a device.
Contributing
Before contributing to CDYelpFusionKit, please read the instructions detailed in our contribution guide.
Usage
Initialization
let yelpAPIClient = CDYelpAPIClient(apiKey: "YOUR_API_KEY")
Once you've created a CDYelpAPIClient object you can use it to query the Yelp Fusion API using any of the following methods.
- Parameters with
// Optional
can take nil as a value. - Parameters with
// Required
will throw an exception when passing nil as a value.
Search Endpoint
public func searchBusinesses(byTerm term: String?, // Optional
location: String?, // Optional
latitude: Double?, // Optional
longitude: Double?, // Optional
radius: Int?, // Optional - Max = 40000
categories: [CDYelpCategoryAlias]?, // Optional
locale: CDYelpLocale?, // Optional
limit: Int?, // Optional - Default = 20, Max = 50
offset: Int?, // Optional
sortBy: CDYelpBusinessSortType?, // Optional - Default = .bestMatch
priceTiers: [CDYelpPriceTier]?, // Optional
openNow: Bool?, // Optional - Default = false
openAt: Int?, // Optional
attributes: [CDYelpAttributeFilter]?, // Optional
completion: @escaping (CDYelpSearchResponse.Business?) -> Void);
The search endpoint has a categories
parameter which allows for query results to be returned based off one thousand four hundred and sixty-one types of categories. The full list of categories can be found in CDYelpEnums.swift
. The following lines of code show an example of a category that can be passed into the categories
parameter.
CDYelpCategoryAlias.activeLife
The search endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. The following lines of code show which locales can be passed into the locale
parameter.
CDYelpLocale.chinese_hongKong
CDYelpLocale.chinese_taiwan
CDYelpLocale.czech_czechRepublic
CDYelpLocale.danish_denmark
CDYelpLocale.dutch_belgium
CDYelpLocale.dutch_theNetherlands
CDYelpLocale.english_australia
CDYelpLocale.english_belgium
CDYelpLocale.english_canada
CDYelpLocale.english_hongKong
CDYelpLocale.english_malaysia
CDYelpLocale.english_newZealand
CDYelpLocale.english_philippines
CDYelpLocale.english_republicOfIreland
CDYelpLocale.english_singapore
CDYelpLocale.english_switzerland
CDYelpLocale.english_unitedKingdom
CDYelpLocale.english_unitedStates
CDYelpLocale.filipino_philippines
CDYelpLocale.finnish_finland
CDYelpLocale.french_belgium
CDYelpLocale.french_canada
CDYelpLocale.french_france
CDYelpLocale.french_switzerland
CDYelpLocale.german_austria
CDYelpLocale.german_germany
CDYelpLocale.german_switzerland
CDYelpLocale.italian_italy
CDYelpLocale.italian_switzerland
CDYelpLocale.japanese_japan
CDYelpLocale.malay_malaysia
CDYelpLocale.norwegian_norway
CDYelpLocale.polish_poland
CDYelpLocale.portuguese_brazil
CDYelpLocale.portuguese_portugal
CDYelpLocale.spanish_argentina
CDYelpLocale.spanish_chile
CDYelpLocale.spanish_mexico
CDYelpLocale.spanish_spain
CDYelpLocale.swedish_finland
CDYelpLocale.swedish_sweden
CDYelpLocale.turkish_turkey
The search endpoint has a sortBy
parameter which allows for query results to be filtered based off four types of criteria. The following lines of code show which sort types can be passed into the sortBy
parameter.
CDYelpBusinessSortType.bestMatch // Default
CDYelpBusinessSortType.rating
CDYelpBusinessSortType.reviewCount
CDYelpBusinessSortType.distance
The search endpoint has a price
parameter which allows for query results to be filtered based off four types of criteria. The following lines of code show which price tiers can be passed into the priceTiers
parameter.
CDYelpPriceTier.oneDollarSign
CDYelpPriceTier.twoDollarSigns
CDYelpPriceTier.threeDollarSigns
CDYelpPriceTier.fourDollarSigns
The search endpoint has an attributes
parameter which allows for query results to be filtered based off five types of criteria. The following lines of code show which attributes can be passed into the attributes
parameter.
CDYelpAttributeFilter.hotAndNew
CDYelpAttributeFilter.requestAQuote
CDYelpAttributeFilter.reservation
CDYelpAttributeFilter.waitlistReservation
CDYelpAttributeFilter.deals
CDYelpAttributeFilter.genderNeutralRestrooms
CDYelpAttributeFilter.openToAll
CDYelpAttributeFilter.wheelchairAccessible
The following lines of code show an example query to the search endpoint.
// Cancel any API requests previously made
yelpAPIClient.cancelAllPendingAPIRequests()
// Query Yelp Fusion API for business results
yelpAPIClient.searchBusinesses(byTerm: "Food",
location: "San Francisco",
latitude: nil,
longitude: nil,
radius: 10000,
categories: [.activeLife, .food],
locale: .english_unitedStates,
limit: 5,
offset: 0,
sortBy: .rating,
priceTiers: [.oneDollarSign, .twoDollarSigns],
openNow: true,
openAt: nil,
attributes: nil) { (response) in
if let response = response,
let businesses = response.businesses,
businesses.count > 0 {
print(businesses)
}
}
Phone Search Endpoint
public func searchBusinesses(byPhoneNumber phoneNumber: String!, // Required
completion: @escaping (CDYelpSearchResponse.Phone?) -> Void)
The following lines of code show an example query to the phone search endpoint.
yelpAPIClient.searchBusinesses(byPhoneNumber: "+14157492060") { (response) in
if let response = response,
let businesses = response.businesses,
businesses.count > 0 {
print(businesses)
}
}
Transaction Search Endpoint
public func searchTransactions(byType type: CDYelpTransactionType!, // Required
location: String?, // Optional
latitude: Double?, // Optional
longitude: Double?, // Optional
completion: @escaping (CDYelpSearchResponse.Transaction?) -> Void)
The transactions search endpoint has a type
parameter which allows for query results to be filtered based off one type of criteria. The following lines of code show which transaction types can be passed into the byType
parameter.
CDYelpTransactionType.foodDelivery
The following lines of code show an example query to the transactions search endpoint.
yelpAPIClient.searchTransactions(byType: .foodDelivery,
location: "San Francisco",
latitude: nil,
longitude: nil) { (response) in
if let response = response,
let businesses = response.businesses,
businesses.count > 0 {
print(businesses)
}
}
Business Endpoint
public func fetchBusiness(forId id: String!, // Required
locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpBusinessResponse?) -> Void)
The following lines of code show an example query to the business endpoint.
yelpAPIClient.fetchBusiness(forId: "north-india-restaurant-san-francisco"
locale: nil) { (business) in
if let response = response,
let business = response.business {
print(business)
}
}
Business Match Endpoint
public func searchBusinesses(name: String!, // Required - Max length = 64
addressOne: String?, // Optional - Max length = 64
addressTwo: String?, // Optional - Max length = 64
addressThree: String?, // Optional - Max length = 64
city: String!, // Required - Max length = 64
state: String!, // Required - Max length = 3
country: String!, // Required - Max length = 2
latitude: Double?, // Optional - Min = -90, Max = +90
longitude: Double?, // Optional - Min = -180, Max = +180
phone: String?, // Optional - Max length = 32
zipCode: String?, // Optional
yelpBusinessId: String?, // Optional
limit: Int?, // Optional - Min = 1, Default = 3, Max = 10
matchThresholdType: CDYelpBusinessMatchThresholdType, // Required
completion: @escaping (CDYelpSearchResponse.BusinessMatch?) -> Void)
The business match endpoint has a matchThresholdType
parameter which allows for query results to be filtered based off three types of criteria. The following lines of code show which business match threshold types can be passed into the matchThresholdType
parameter.
CDYelpBusinessMatchThresholdType.none
CDYelpBusinessMatchThresholdType.normal
CDYelpBusinessMatchThresholdType.strict
The following lines of code show an example query to the business match endpoint.
yelpAPIClient.searchBusinesses(name: "Gary Danko",
addressOne: "800 N Point St",
addressTwo: nil,
addressThree: nil,
city: "San Francisco",
state: "CA",
country: "US",
latitude: nil,
longitude: nil,
phone: nil,
zipCode: nil,
yelpBusinessId: nil,
limit: 5,
matchThresholdType: .normal) { (response) in
if let response = response,
let businesses = response.businesses,
businesses.count > 0 {
print(businesses)
}
}
Reviews Endpoint
public func fetchReviews(forBusinessId id: String!, // Required
locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpReviewsResponse?) -> Void)
The reviews endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the reviews endpoint.
yelpAPIClient.fetchReviews(forBusinessId: "north-india-restaurant-san-francisco",
locale: nil) { (reviews) in
if let response = response,
let reviews = response.reviews,
reviews.count > 0 {
print(reviews)
}
}
Autocomplete Endpoint
public func autocompleteBusinesses(byText text: String!, // Required
latitude: Double!, // Required
longitude: Double!, // Required
locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpAutoCompleteResponse?) -> Void)
The autocomplete endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the autocomplete endpoint.
yelpAPIClient.autocompleteBusinesses(byText: "Pizza Delivery",
latitude: 37.786572,
longitude: -122.415192,
locale: nil) { (response) in
if let response = response,
let businesses = response.businesses,
businesses.count > 0 {
print(businesses)
}
}
Event Lookup Endpoint
public func fetchEvent(forId id: String!, // Required
locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpEventResponse?) -> Void)
The event lookup endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the event lookup endpoint.
yelpAPIClient.fetchEvent(forId: "san-francisco-yelp-celebrates-pride-month-2021",
locale: nil) { (event) in
if let response = response,
event = response.event {
print(event)
}
}
Event Search Endpoint
public func searchEvents(byLocale locale: CDYelpLocale?, // Optional
offset: Int?, // Optional
limit: Int?, // Optional - Default = 3, Max = 50
sortBy: CDYelpEventSortByType?, // Optional - Default = .descending
sortOn: CDYelpEventSortOnType?, // Optional - Default = .popularity
startDate: Date?, // Optional
endDate: Date?, // Optional
categories: [CDYelpEventCategoryFilter]?, // Optional
isFree: Bool?, // Optional - Default = false
location: String?, // Optional
latitude: Double?, // Optional
longitude: Double?, // Optional
radius: Int?, // Optional - Max = 40000
excludedEvents: [String]?, // Optional
completion: @escaping (CDYelpEventsResponse?) -> Void)
The event search endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The event search endpoint has a sortBy
parameter which allows for query results to be filtered based off two types of criteria. The following lines of code show which sort types can be passed into the sortBy
parameter.
CDYelpEventSortByType.ascending
CDYelpEventSortByType.descending // Default
The event search endpoint has a sortOn
parameter which allows for query results to be filtered based off two types of criteria. The following lines of code show which sort types can be passed into the sortBy
parameter.
CDYelpEventSortOnType.popularity // Default
CDYelpEventSortOnType.timeStart
The event search endpoint has a categories
parameter which allows for query results to be returned based off thirteen types of categories. The following lines of code show which category types can be passed into the categories
parameter.
CDYelpEventCategoryFilter.charities
CDYelpEventCategoryFilter.fashion
CDYelpEventCategoryFilter.festivalsAndFairs
CDYelpEventCategoryFilter.film
CDYelpEventCategoryFilter.foodAndDrink
CDYelpEventCategoryFilter.kidsAndFamily
CDYelpEventCategoryFilter.lecturesAndBooks
CDYelpEventCategoryFilter.music
CDYelpEventCategoryFilter.nightlife
CDYelpEventCategoryFilter.other
CDYelpEventCategoryFilter.performingArts
CDYelpEventCategoryFilter.sportsAndActiveLife
CDYelpEventCategoryFilter.visualArts
The following lines of code show an example query to the event search endpoint.
yelpAPIClient.searchEvents(byLocale: nil,
offset: nil,
limit: 5,
sortBy: .descending,
sortOn: .popularity,
startDate: nil,
endDate: nil,
categories: [.music, .foodAndDrink],
isFree: false,
location: nil,
latitude: 37.786572,
longitude: -122.415192,
radius: 10000,
excludedEvents: nil) { (response) in
if let response = response,
let events = response.events,
events.count > 0 {
print(events)
}
}
Featured Event Endpoint
public func fetchFeaturedEvent(forLocale locale: CDYelpLocale?, // Optional
location: String?, // Optional
latitude: Double?, // Optional
longitude: Double?, // Optional
completion: @escaping (CDYelpEventResponse?) -> Void)
The featured event endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the featured event endpoint.
yelpAPIClient.fetchFeaturedEvent(forLocale: nil,
location: nil,
latitude: 37.786572,
longitude: -122.415192) { (event) in
if let response = response,
event = response.event {
print(event)
}
}
All Categories Endpoint
public func fetchCategories(forLocale locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpCategoriesResponse?) -> Void)
The all categories endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the featured event endpoint.
yelpAPIClient.fetchCategories(forLocale: nil) { (response) in
if let response = response,
let categories = response.categories {
print(categories)
}
}
Category Details Endpoint
public func fetchCategory(forAlias alias: CDYelpCategoryAlias!, // Required
andLocale locale: CDYelpLocale?, // Optional
completion: @escaping (CDYelpCategoryResponse?) -> Void)
The category details endpoint has an alias
parameter which allows for query results to be returned based off one thousand four hundred and sixty-one types of categories. The full list of categories can be found in CDYelpEnums.swift
. The following lines of code show an example of a category that can be passed into the alias
parameter.
CDYelpCategoryAlias.activeLife
The category details endpoint has a locale
parameter which allows for query results to be returned based off forty-two types of language and country codes. Refer to the search endpoint for information regarding using the locale
parameter.
The following lines of code show an example query to the featured event endpoint.
yelpAPIClient.fetchCategory(forAlias: .fastFood,
andLocale: nil) { (response) in
if let response = response,
let category = response.category {
print(category)
}
}
Deep Linking
The Yelp iPhone application registers URL schemes that can be used to open the Yelp application, perform searches, view business information, or check-in.
static func yelpDeepLink() -> URL?
The following lines of code show an example of how to check if the Yelp application is installed and then open it.
if let url = URL.yelpDeepLink(),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Search
static func yelpSearchDeepLink(withTerm term: String?, // Optional
category: CDYelpCategoryAlias?, // Optional
location: String?) -> URL? // Optional
The search deep link has a category
parameter which allows for query results to be returned based off one thousand four hundred and sixty-one types of categories. Refer to the search endpoint for information regarding using the category
parameter.
The following lines of code show an example query to the search deep link.
if let url = URL.yelpSearchDeepLink(withTerm: "burrito",
category: .food,
location: "San Francisco, CA"),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Business
static func yelpBusinessDeepLink(forId id: String!) -> URL? // Required
The following lines of code show an example query to the business deep link.
if let url = URL.yelpBusinessDeepLink(forId: "the-sentinel-san-francisco"),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Check In Nearby
static func yelpCheckInNearbyDeepLink() -> URL?
The following lines of code show an example query to the check in nearby deep link.
if let url = URL.yelpCheckInNearbyDeepLink(),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Check-Ins
static func yelpCheckInsDeepLink() -> URL?
The following lines of code show an example query to the check-ins deep link.
if let url = URL.yelpCheckInsDeepLink(),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Check-In Rankings
static func yelpCheckInRankingsDeepLink() -> URL?
The following lines of code show an example query to the check-in rankings deep link.
if let url = URL.yelpCheckInRankingsDeepLink(),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Web Linking
The Yelp website registers URL schemes that can be used to open the Yelp website, perform searches or view business information.
static func yelpWebLink() -> URL?
The following lines of code show an example of how to open the Yelp website.
if let url = URL.yelpWebLink(),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Search
static func yelpSearchWebLink(withTerm term: String?, // Optional
category: CDYelpCategoryAlias?, // Optional
location: String?) -> URL? // Optional
The search deep link has a category
parameter which allows for query results to be returned based off one thousand four hundred and sixty-one types of categories. Refer to the search endpoint for information regarding using the category
parameter.
The following lines of code show an example query to the search web link.
if let url = URL.yelpSearchWebLink(withTerm: "burrito",
category: .food,
location: "San Francisco, CA"),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Business
static func yelpBusinessWebLink(forId id: String!) -> URL? // Required
The following lines of code show an example query to the business web link.
if let url = URL.yelpBusinessWebLink(forId: "the-sentinel-san-francisco"),
UIApplication.shared.canOpenURL(url) {
UIApplication.shared.open(url,
options: [:],
completionHandler: nil)
}
Brand Assets
The Yelp brand guidelines exist to achieve consistency and make sure the branded elements of Yelp are used correctly across every application.
Color
class func yelpFiveStarRed() -> UIColor
The following lines of code show an example of how to use the brand color.
cell.textLabel?.textColor = UIColor.yelpFiveStarRed()
Logo
class func yelpLogo() -> UIImage?
class func yelpLogoOutline() -> UIImage?
class func yelpBurstLogoRed() -> UIImage?
class func yelpBurstLogoWhite() -> UIImage?
The following lines of code show examples of how to use the brand logo and the brand burst logo.
cell.imageView?.image = UIImage.yelpLogo()
cell.imageView?.image = UIImage.yelpLogoOutline()
cell.imageView?.image = UIImage.yelpBurstLogoRed()
cell.imageView?.image = UIImage.yelpBurstLogoWhite()
Stars
class func yelpStars(numberOfStars: CDYelpStars!,
forSize size: CDYelpStarsSize!) -> UIImage?
The stars image has a numberOfStars
parameter which defines the number of filled stars in the returned image. The following lines of code show which number of stars can be passed into the numberOfStars
parameter.
CDYelpStars.zero
CDYelpStars.one
CDYelpStars.oneHalf
CDYelpStars.two
CDYelpStars.twoHalf
CDYelpStars.three
CDYelpStars.threeHalf
CDYelpStars.four
CDYelpStars.fourHalf
CDYelpStars.five
The stars image has a forSize
parameter which defines the size of the returned image. The following lines of code show which sizes can be passed into the forSize
parameter.
CDYelpStarsSize.small
CDYelpStarsSize.regular
CDYelpStarsSize.large
CDYelpStarsSize.extraLarge
The following lines of code show an example of how to use the stars image.
cell.imageView?.image = UIImage.yelpStars(numberOfStars: .twoHalf, forSize: .large)
Author
Christopher de Haan, [email protected]
Resources
Visit the Yelp Developers portal for additional resources regarding the Yelp API.
License
CDYelpFusionKit is available under the MIT license. See the LICENSE file for more info.