Class: Unsplash::Photo

Inherits:
Client
  • Object
show all
Defined in:
lib/unsplash/photo.rb

Overview

Unsplash Photo operations.

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Client

#connection, connection, connection=, #initialize, #reload!, #to_h

Constructor Details

This class inherits a constructor from Unsplash::Client

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Unsplash::Client

Class Method Details

.all(page = 1, per_page = 10, order_by = "latest") ⇒ Array

Get a list of all photos.

Parameters:

  • page (Integer) (defaults to: 1) —

    Which page of search results to return.

  • per_page (Integer) (defaults to: 10) —

    The number of search results per page. (default: 10, maximum: 30)

  • order_by (String) (defaults to: "latest") —

    How to sort the photos. (Valid values: latest, oldest, popular; default: latest)

Returns:

  • (Array) —

    A single page of Unsplash::Photo search results.



103
104
105
106
107
108
109
110
 
# File 'lib/unsplash/photo.rb', line 103

def all(page = 1, per_page = 10, order_by = "latest")
  params = {
    page:     page,
    per_page: per_page,
    order_by: order_by
  }
  parse_list connection.get("/photos/", params).body
end

.create(filepath) ⇒ Unsplash::Photo

Upload a photo on behalf of the current user. DEPRECATED

Parameters:

  • filepath (String) —

    The local path of the image file to upload.

Returns:



130
131
132
 
# File 'lib/unsplash/photo.rb', line 130

def create(filepath)
  raise Unsplash::DeprecationError.new "API photo-upload endpoint has been deprecated and removed."
end

.curated(page = 1, per_page = 10, order_by = "latest") ⇒ Array

Get a single page from the list of the curated photos (front-page’s photos).

Parameters:

  • page (Integer) (defaults to: 1) —

    Which page of search results to return.

  • per_page (Integer) (defaults to: 10) —

    The number of search results per page. (default: 10, maximum: 30)

  • order_by (String) (defaults to: "latest") —

    How to sort the photos. (Valid values: latest, oldest, popular; default: latest)

Returns:

  • (Array) —

    A single page of Unsplash::Photo search results.



117
118
119
120
121
122
123
124
 
# File 'lib/unsplash/photo.rb', line 117

def curated(page = 1, per_page = 10, order_by = "latest")
  params = {
    page:     page,
    per_page: per_page,
    order_by: order_by
  }
  parse_list connection.get("/photos/curated", params).body
end

.find(id, width: nil, height: nil, crop_rect: nil) ⇒ Unsplash::Photo

Get a photo. Can be cropped or resized using the optional parameters.

Parameters:

  • id (String) —

    The ID of the photo to retrieve.

  • width (Integer) (defaults to: nil) —

    Width of customized version of the photo.

  • height (Integer) (defaults to: nil) —

    Height of the customized version of the photo.

  • crop_rect (String) (defaults to: nil) —

    A comma-separated list (x,y,width,height) of the rectangle to crop from the photo.

Returns:



34
35
36
37
38
39
40
41
42
43
 
# File 'lib/unsplash/photo.rb', line 34

def find(id, width: nil, height: nil, crop_rect: nil)
  custom = {
    w:    width,
    h:    height,
    rect: crop_rect
  }.select { |k,v| v }
  photo = Unsplash::Photo.new JSON.parse(connection.get("/photos/#{id}", custom).body)
  photo.user = Unsplash::User.new photo.user
  photo
end

.random(count: nil, categories: nil, collections: nil, featured: nil, user: nil, query: nil, width: nil, height: nil, orientation: nil) ⇒ Unsplash::Photo, Array

Get a random photo or set of photos. The photo selection pool can be narrowed using a combination of optional parameters. Can also optionally specify a custom image size.

Parameters:

  • count (Integer) (defaults to: nil) —

    Number of photos required. Default=1, Max=30

  • categories (Array) (defaults to: nil) —

    Limit selection to given category ID’s.

  • featured (Boolean) (defaults to: nil) —

    Limit selection to featured photos.

  • user (String) (defaults to: nil) —

    Limit selection to given User’s ID.

  • query (String) (defaults to: nil) —

    Limit selection to given search query.

  • width (Integer) (defaults to: nil) —

    Width of customized version of the photo.

  • height (Integer) (defaults to: nil) —

    Height of the customized version of the photo.

  • orientation (String) (defaults to: nil) —

    Filter by orientation of the photo. Valid values are landscape, portrait, and squarish.

Returns:

  • (Unsplash::Photo) —

    An Unsplash Photo if count parameter is omitted

  • (Array) —

    An array of Unsplash Photos if the count parameter is specified. An array is returned even if count is 1



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/unsplash/photo.rb', line 57

def random(count: nil, categories: nil, collections: nil, featured: nil, user: nil, query: nil, width: nil, height: nil, orientation: nil)
  params = {
    category: (categories && categories.join(",")),
    collections: (collections && collections.join(",")),
    featured: featured,
    username: user,
    query:    query,
    w:        width,
    h:        height,
    orientation: orientation
  }.select { |k,v| v }
  if count
    params[:count] = count
    photos = parse_list connection.get("/photos/random/", params).body
    photos.map { |photo|
      photo.user = Unsplash::User.new photo[:user]
      photo
    }
  else
    photo = Unsplash::Photo.new JSON.parse(connection.get("/photos/random", params).body)
    photo.user = Unsplash::User.new photo.user
    photo
  end
end

.search(query, page = 1, per_page = 10, orientation = nil) ⇒ SearchResult

Search for photos by keyword.

Parameters:

  • query (String) —

    Keywords to search for.

  • page (Integer) (defaults to: 1) —

    Which page of search results to return.

  • per_page (Integer) (defaults to: 10) —

    The number of users search result per page. (default: 10, maximum: 30)

  • orientation (String) (defaults to: nil) —

    Filter by orientation of the photo. Valid values are landscape, portrait, and squarish.

Returns:



88
89
90
91
92
93
94
95
96
 
# File 'lib/unsplash/photo.rb', line 88

def search(query, page = 1, per_page = 10, orientation = nil)
  params = {
    query:    query,
    page:     page,
    per_page: per_page,
    orientation: orientation
  }.select { |_k, v| v }
  Unsplash::Search.search("/search/photos", self, params)
end

Instance Method Details

#download! ⇒ String

Download a photo.

Returns:

  • (String) —

    URL of image file for download.



22
23
24
 
# File 'lib/unsplash/photo.rb', line 22

def download!
  connection.get(links.download_location)["url"]
end

#like! ⇒ Boolean

Like a photo for the current user.

Returns:

  • (Boolean) —

    True if successful. Will raise on error.



8
9
10
11
 
# File 'lib/unsplash/photo.rb', line 8

def like!
  connection.post("/photos/#{id}/like")
  true
end

#unlike! ⇒ Boolean

Unlike a photo for the current user.

Returns:

  • (Boolean) —

    True if successful. Will raise on error.



15
16
17
18
 
# File 'lib/unsplash/photo.rb', line 15

def unlike!
  connection.delete("/photos/#{id}/like")
  true
end