unsplasharp
unsplasharp copied to clipboard
C# API wrapper around Unsplash 📷
Unsplasharp 📷
⚠️ Looking for maintenairs I don't have much time to work on this lib.
Unofficial C# wrapper around Unsplash API targeting .NET Standard 1.4.
This lib is compatible with .NET Core, .NET Framework 4.6.1, Xamarin (iOS, Android), Universal Windows Platform.
Currently incomplete 🚧
- Missing user's authentication actions
Installation
NuGet: Install-Package unsplasharp.api
Usage
using Unsplasharp;
var client = new UnsplasharpClient("YOUR_APPLICATION_ID");
var photosFound = await client.SearchPhoto("mountains");
API documentation
Instanciate a new client
It's necessary to instanciate a new client with at least an application ID to start making requests.
var client = new Client("YOUR_APPLICATION_ID");
General
Rates limits
Unsplash has API requests rates limits.
An Unsplashsharp client has two properties to help you monitor API calls:
Max API calls allowed per hour
-
MaxRateLimit
API calls remaining for the current hour
-
RateLimitRemaining
if (client.RateLimitRemaining == 0) {
// Warning the user that he's to wait some time
// before using the app again.
}
if (client.MaxRateLimit == 50) {
// Application is in dev mode.
} else if (client.MaxRateLimit == 5000) {
// Application is in prod mode.
} else { /* Unknown mode */ }
Photos
Get a single photo from an id
var photo = await client.GetPhoto("TPv9dh822VA");
// get a photo in the specified width and height in pixels
var photoWidthHeight = await client.GetPhoto(id: "TPv9dh822VA", width: 500, height: 500);
Get a random photo
var randomPhoto = await client.GetRandomPhoto();
// using collections' IDs
var randomPhotoFromCollections = await client.GetRandomPhoto(new string[] { "499830", "194162" });
// from a specific user
var randomPhotoFromUser = await client.GetRandomPhoto(count: 1, username: "matthewkane");
var randomPhotosFromQuery = await client.GetRandomPhoto(count: 3, query:"woman");
Get a list of all photos
var listPhotos = await client.ListPhotos();
var listPhotosPaged = await client.ListPhotos(page:2, perPage:15, orderBy: OrderBy.Popular);
Collections
Get a single collection from an id
var collection = await client.GetCollection("771520");
Get a list of all collections
var listCollection = await client.ListCollections();
Get a list of featured collections
var listFeaturedCollection = await client.ListFeaturedCollections();
Get a collection's photos from a collection's id
var listPhotos = await client.GetCollectionPhotos("771520");
Get related collections from a collection's id
var collectionsRelated = await client.ListRelatedCollections("771520");
Users
Get a single user from his/her username
var user = await client.GetUser("unsplash");
var userCustomProfileImage = client.GetUser("seteales", width: 100, height: 100);
Get a list of user's collections
var userCollections = await client.ListUserCollections("unsplash");
Get a list of user's photos
var userPhotos = await client.ListUserPhotos("seteales");
var userPhotosCustomParam = await client.ListUserPhotos("seteales", page: 2, perPage: 2, stats: true);
Get a list of user's liked photos
var userLikedPhotos = await client.ListUserLikedPhotos("seteales");
Get an user's statistics
var userStats = await client.GetUserStats("seteales");
Search
Search photos from a query
var photosFound = await client.SearchPhoto("mountains");
Search collections from a query
var collectionsFound = await client.SearchCollections("mountains");
Search users from a query
var usersFound = await client.SearchUsers("seteales");
Stats
Get Unsplash total stats
var totalStats = await client.GetTotalStats();
Get Unsplash monthly stats
var monthlyStats = await client.GetMonthlyStats();
Custom Requests
In adition to the previous API methods, you can build and use custom URL's to fetch photos, photos' lists, and collections' lists.
There're also methods to search for collections, photos and users using a custom URL.
Fetch a photo
var photo = await client.FetchPhoto("you_custom_url");
Fetch a list of photos
var photos = await client.FetchPhotosList("you_custom_url");
Fetch a list of collections
var collections = await client.FetchCollectionsList("you_custom_url");
Search for photos using a specific search URL
var photosFound = await client.FetchSearchPhotosList("your_custom_url");
Search for collections using a specific search URL
var collectionsFound = await client.FetchSearcCollectionsList("your_custom_url");
Search for users using a specific search URL
var usersFound = await client.FetchSearcUsersList("your_custom_url");
Tests
Tests are under UnsplashsharpTests project.
They check the Unsplash API status and that every methods in the lib works properly.
In this project, a dev API key is used which is limited to 50 requests per hour. So ensure you're not off limit.
Personal API key
If you want to get your personal API key from Unsplash:
- Go to Unsplash
- Log in or create a new account
- In the top bar, click on 'API/Developers'
- Go to 'Your applications'
- Click on 'New Application' to create a new one and get an API key (and a Secret).