Skip to content

About

A wrapper around Unsplash's (https://unsplash.com) API. Written with love in Go.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

193 Commits

Folders and files

Repository files navigation

Unsplash API wrapper

Build Status Go Report Card Go Reference codecov

A simple wrapper around the unsplash API.

Documentation

Installation

go get github.com/eddogola/unsplash-go/unsplash

API Guidelines

When using the Unsplash API, you need to make sure to abide by their API guidelines and API Terms.

Registration

Sign up on Unsplash.com and register as a developer. You can then create a new application and use the AppID and Secret for authentication.

Usage

Importing

Once you've installed the library using go get, import it as follows

import (
    "github.com/eddogola/unsplash-go/unsplash"
    "github.com/eddogola/unsplash-go/unsplash/client"
)

Create Unsplash instance

import (
    "github.com/eddogola/unsplash-go/unsplash"
    "github.com/eddogola/unsplash-go/unsplash/client"
)

unsplash := unsplash.New(client.New(
  os.Getenv("CLIENT_ID"), // <YOUR-CLIENT-ID>
  nil, // when nil is passed, http.DefaultClient is used
  client.NewConfig(),
  ))

unsplash.Photos

Photos.All

Get a paginated list of all unsplash Photos.

pics, err := unsplash.Photos.All(nil)

Photos.Get

Get a specific photo.

pic, err := unsplash.Photos.Get(`photo-id`)

Photos.Random

Get a random photo. Returns an interface depending on whether the count query parameter is provided. If present, a list of photos is returned, otherwise, a single photo is returned

count not provided
res, err := unsplash.Photos.Random(nil)
randomPhoto := res.(*client.Photo)
count provided
res, err := unsplash.Photos.Random(client.QueryParams{"count": "1"})
randomPhotos := res.([]client.Photo)

Photos.Stats

Get a specific photo's stats. Returns a *client.PhotoStats object.

stats, err := unsplash.Photos.Stats(pics[0].ID, nil)

Photos.Search

Search photos. Returns a *client.PhotoSearchResults object.

searchResult, err := unsplash.Photos.Search("food", nil)
fmt.Println(searchResult.Results)

unsplash.Users

Users.PublicProfile

Get a user's public profile. Returns a *client.User object.

profile, err := unsplash.Users.PublicProfile(`username`)

Users.PortfolioURL

Parses a user's portoflio URL, returning it in a *url.URL object.

url, err := unsplash.Users.PortfolioURL(`username`)

Users.Photos

Get a user's photos.

photos, err := unsplash.Users.Photos(`username`, nil)

Users.LikedPhotos

Get a user's liked photos.

likedPhotos, err := unsplash.Users.LikedPhotos(`username`, nil)

Users.Collections

Get collections created by user.

collections, err := unsplash.Users.Collections(`username`, nil)

Users.Stats

Get a user's stats. Returns a *client.UserStats object.

stats, err := unsplash.Users.Stats(username, nil)

Users.Search

Search for a user. Returns search results in a *client.UserSearchResults object

searchResult, err := unsplash.Users.Search(`username`, nil)
fmt.Println(searchResult.Results)

unsplash.Collections

Collections.All

Returns a list of all collections.

collections, err := unsplash.Collections.All(nil)

Collections.Get

Get a specific collection

collection, err := unsplash.Collections.Get(`collectionID`)

Collections.Photos

Returns the given collection's photos.

photos, err := unsplash.Collections.Photos(`collectionID`, nil)

Collections.Related

Returns a list of collections related to the given collection.

related, err := unsplash.Collections.Related(`collectionID`)

Collections.Search

Returns the results of searching a collection in a *client.CollectionSearchResult object.

searchResults, err := unsplash.Collections.Search("code", nil)

unsplash.Topics

Topics.All

Returns a list of all topics.

topics, err := unsplash.Topics.All(nil)

Topics.Get

Returns a specific *client.Topic object, given the topic's ID.

topic, err := unsplash.Topics.Get(`topicID`)

Topics.Photos

Returns a list of *client.Photos in the given the topic's ID.

photos, err := unsplash.Topics.Photos(`topicID`, nil)

Examples

Find examples on Github

Authentication

The user's client ID is passed in Authorization headers by default, not query parameters.

Buggy areas

Private client authentication not fully functional.

Potential areas of improvement

pagination not yet implemented. The below code can exemplifies a way to work around pagination. Suggestions are welcome.\

package unsplash

import (
 "context"
"fmt"
"net/http"

"github.com/eddogola/unsplash-go/unsplash"
"github.com/eddogola/unsplash-go/unsplash/client"
)

// an example of getting photos in the subsequent pages
func getPics() {
// library initialization
clientID := "<YOUR-CLIENT-ID>"
cl := client.NewClient(clientID, http.DefaultClient, client.NewConfig())
unsplash := unsplash.New(cl)

// query parameters to be passed to the request
qParams := client.QueryParams(map[string]string{
    "order_by": "latest",
})

var photos []Photo
// get the first five pages
for i := 0; i <= 5; i++ {
    qParams["page"] = fmt.Sprint(i)
    pics, err := cl.GetPhotoList(context.Background(), qParams)
    photos = append(photos, pics...)
}
}

About

A wrapper around Unsplash's (https://unsplash.com) API. Written with love in Go.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages

⌂ 换网址