Unsplash API client written in Swift.
Unsplash offers 2 APIs:
- Source API (unlimited requests)
- Official API
- JSON API (5000 requests / hour)
JSON API is in progress and will be available soon in this library.
Requirements
- iOS 8.0+ / Mac OS X 10.9+ / tvOS 9.0+ / watchOS 2.0+
- Xcode 8.0+
Installation
You can use CocoaPods to integrate the library with your project.
pod "UnsplashKit/API" # Official API
pod "UnsplashKit/Source" # Source API
Usage
import UnsplashKit
Official API
First thing you need is an instance of the client for executing requests and parsing responses from the API:
var token = "xxxx"
var client = UnsplashClient { request -> [String: String] in
return [ "Authorization": "Bearer \(token)"]
}
Since the client supports providing headers for the requests, we'll use that closure to specify the authenticationt tokent that we want to pass in. UnsplashKit doesn't provide the OAuth2 authentication components, but you can use Paparajote instead.
Resources
Once the client is created you can use models' resources that contain the information about the request and about how to parse the JSON response into models whose properties you can access directly to. Here's an example:
let searchPhotos = Search.photos(query: "mountain")
client.execute(resource: searchPhotos) { (result) in
print(result)
}
The models that contain resources are,
User,Photo,Search,Collection. These resources match the endpoints available from the API. If there's any new endpoint which is not supported, you can either create an issue, open a PR or contact [email protected]
Source API
Source API allows you to get an Unsplash image in different ways.
Results
All the calls return the image through a completion block that returns a Result<Image, Error>.
call() { result in
switch result {
case .success(let image): //handle image
case .failure(let error): //handle error
}
}
You can also ignore the error and get only the result using
call() { result in
let image = result.value
}
Random photo
UnsplashSource().randomPhoto() { result in
// handle the result
}
Random from a category
UnsplashSource().randomPhoto(fromCategory: .nature) { result in
// handle the result
}
Unsplash offers a list of predefined categories. You can ask for a photo from any of these categories.
.buildings
.food
.nature
.people
.technology
.objects
Random from a specific user
UnsplashSource().randomPhoto(fromUser: "carambalabs") { result in
// handle the result
}
Random from a user's likes
UnsplashSource().randomPhoto(fromUserLikes: "mkwlsn") { result in
// handle the image
}
Random from a collection
UnsplashSource().randomPhoto(fromCollection: "176316") { result in
// handle the result
}
Random search term
UnsplashSource().randomPhoto(fromSearch: ["nature", "water"]) { result in
// handle the result
}
Specific photo
UnsplashSource().photo("WLUHO9A_xik") { result in
// handle the result
}
Specific image size
If you want to get an image of a specific size you can use the optional size parameter in any call.
UnsplashSource().randomPhoto(fromCategory: .nature, size: CGSize(width: 600, height: 200)) { result in
// handle the result
}
Fixed daily/weekly photo
The calls random, search, category and user can also be limited to only updating once per day or week. To do so, simply use the optional filter parameter.
UnsplashSource().randomPhoto(filter: .daily) { result in
// handle the result
}
About
This project is funded and maintained by Caramba. We
Check out our other open source projects, read our blog or say
Contribute
Contributions are welcome
License
UnsplashKit is available under the MIT license. See the LICENSE file for more info.
184 Nov 25, 2022
579 Dec 31, 2022
2 Dec 1, 2019
52 Jul 11, 2019
61 Dec 21, 2022
100 Jan 6, 2023
171 Jun 18, 2022
105 Nov 16, 2022
11 Jan 22, 2022
2.4k Dec 30, 2022
1k Dec 20, 2022
95 Sep 9, 2022
8 Nov 1, 2016
131 Nov 23, 2022
107 Nov 8, 2022
8 Apr 5, 2021
19 Jun 28, 2022
8 May 12, 2019