• API parameter resizing deprecation

    The custom cropping and resizing parameters accepted by the get a photo, get a random photo, and get a user endpoints are being deprecated and replaced instead with dynamic image URLs which are capable of more resizing and cropping options.

    The photo.url.custom attribute is also being deprecated, as it is no longer needed.

  • Abbreviation of top photos in users search and user endpoints

    For performance reasons we are removing some of the deeply-nested photo objects returned in the search/users and users/:username endpoints.

    Previously, the user object contained an array of the top 3 photos, which included a full photo response for each photo:

    {
      "id": "s6-TQxOxDSA",
      "created_at": "2016-01-27T07:55:40-05:00",
      "width": 2448,
      "height": 2448,
      "color": "#E8F4F9",
      "likes": 0,
      "liked_by_user": false,
      "description": "A man drinking a coffee.",
      "current_user_collections": [],
      "urls": {
          "raw": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8",
          "full": "https://hd.unsplash.com/photo-1453899242646-c74d86b5b8e8",
          "regular": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=05993ddfa31268c29b2e7e253d9b112b",
          "small": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=2d0bd4cef8c2955243273764ca953dcf",
          "thumb": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=a1d5d225a733ed19574b97b701d9e20f"
        },
      "links": {
        "self": "https://api.unsplash.com/photos/s6-TQxOxDSA",
        "html": "http://unsplash.com/photos/s6-TQxOxDSA",
        "download": "http://unsplash.com/photos/s6-TQxOxDSA/download"
      }
    }
    

    Going forward, the new shape of these top 3 photos will be abbreviated to:

    {
      "id": "s6-TQxOxDSA",
      "urls": {
        "raw": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8",
        "full": "https://hd.unsplash.com/photo-1453899242646-c74d86b5b8e8",
        "regular": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&s=05993ddfa31268c29b2e7e253d9b112b",
        "small": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=400&fit=max&s=2d0bd4cef8c2955243273764ca953dcf",
        "thumb": "https://images.unsplash.com/photo-1453899242646-c74d86b5b8e8?ixlib=rb-0.3.5&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=200&fit=max&s=a1d5d225a733ed19574b97b701d9e20f"
      }
    }
    

    To get a list of full photo objects for a user, instead hit the users/:username/photos endpoint.

  • Categories removal

    Categories endpoints have been removed.

  • Curated Collections deprecation

    Curated Collections are now deprecated. This includes endpoints:

    • GET /collections/curated
    • GET /collections/curated/:id
    • GET /collections/curated/:id/photos
    • GET /photos/curated

    Existing curated collections will continue to be returned from these endpoints, but no new data will be added. They are now also included in the regular /collections endpoints.

  • Abbreviation of current_user_collections

    For performance reasons we are removing some of the deeply-nested objects returned in the current_user_collections photo attribute. current_user_collections returns a list of collection objects, which will no longer include the user or cover_photo information.

    This change only affects requests made by logged-in users. Logged-out requests (i.e., those made with Client-ID authorization) will see no change.

  • Categories EOL

    Categories endpoints won’t yet 404, but are returning empty data structures. e.g., /categories/:id/photos => []

  • Instagram username now public

    Both full and abbreviated user responses now include the instagram_username attribute without requiring the read_user scope.

  • Filter photo search results by orientation

    The /search and /search/photos/ endpoints will now accept an orientation parameter, and return photos only matching that. Valid values are landscape, portrait, and squarish.

  • Updated API Guidelines

    We’ve updated the official Unsplash API Guidelines to include two new technical guidelines for all API applications:

    • All API uses must use the hotlinked image URLs returned by the API under the photo.urls properties. More info & examples →
    • When your application performs something similar to a download (like when a user chooses the image to include in a blog post, set as a wallpaper, etc.), you must send a request to the download endpoint returned under the photo.links.download_location property. More info & examples →

    View more about the API Guidelines →

  • Existing deprecations

    Some endpoints and behaviour have already been deprecated, and are no longer officially supported:

  • Reactor online. Initializing API changelog.

    We’ll be posting changes to the API starting from here. You can always find the current state of our API at https://unsplash.com/documentation