Unsplasharp 📷

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

Official API documentation

• General
• Photos
• Collections
• Users
• Search
• Stats
• Custom Requests

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);

Get a list of curated photos

var listCuratedPhotos = await client.ListCuratedPhotos();

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 list of curated collections

var listCuratedCollection = await client.ListCuratedCollections();

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:

1. Go to Unsplash
2. Log in or create a new account
3. In the top bar, click on 'API/Developers'
4. Go to 'Your applications'
5. Click on 'New Application' to create a new one and get an API key (and a Secret).

Dependencies

• System.Net.Http
• Newtonsoft.Json

Resources

• Official Unsplash documentation

TODO

• Add user's authentication actions