• Unsplash Source being deprecated

    Unsplash Source is being deprecated. Existing uses will continue to work, however for new projects use the full Unsplash API.

  • Tags property from search endpoints deprecation

    The tags property from the /search and /search/photos endpoint is deprecated and will eventually be removed. This was an undocumented field and is superseded by tags_preview

  • GET /collections/featured removal

    Following up on its deprecation in September, GET /collections/featured has been removed.

  • Query string added to photo download_location URL

    Query string parameters have been added to the photo’s download_location URL. This may cause issues for client implementations adding their access token to the URL via string concatenation.

  • BlurHash added to photo objects

    All photo objects from the Unsplash API now include a blur_hash string. This is a compact representation of an image which can be used as a placeholder before the real image loads.

    For more information on BlurHash and how to use it on your application, check its official page.

  • Added topic endpoints

    We have added new endpoints for topics:

    • GET /topics to obtain a list of all the topics.
    • GET /topics/:id_or_slug to retrieve a single topic details.
    • GET /topic/:id_or_slug/photos to retrieve a topic’s photos.

    For more information on these endpoints and their available params, see the API documentation on topics.

  • Collections ID change and featured deprecation

    Two changes to the Collections API:

    • IDs returned are currently integers, but will be changing to alphanumeric strings.

    • GET /collections/featured has been deprecated. Clients should switch to GET /collections; these endpoints already return identical results.

  • Support for languages beta

    We are adding support for non-english input languages to the search endpoint.

    It is currently in beta, so access is restricted to certain API applications. To access the beta, email api@unsplash.com with your application ID.

    Currently we are adding support for 108 languages:

    ISO 639-1 Language Code Language
    af Afrikaans
    am Amharic
    ar Arabic
    az Azerbaijani
    be Belarusian
    bg Bulgarian
    bn Bengali
    bs Bosnian
    ca Catalan
    ceb Cebuano
    co Corsican
    cs Czech
    cy Welsh
    da Danish
    de German
    el Greek
    en English
    eo Esperanto
    es Spanish
    et Estonian
    eu Basque
    fa Persian
    fi Finnish
    fr French
    fy Frisian
    ga Irish
    gd Scots Gaelic
    gl Galician
    gu Gujarati
    ha Hausa
    haw Hawaiian
    hi Hindi
    hmn Hmong
    hr Croatian
    ht Haitian Creole
    hu Hungarian
    hy Armenian
    id Indonesian
    ig Igbo
    is Icelandic
    it Italian
    iw Hebrew
    ja Japanese
    jw Javanese
    ka Georgian
    kk Kazakh
    km Khmer
    kn Kannada
    ko Korean
    ku Kurdish
    ky Kyrgyz
    la Latin
    lb Luxembourgish
    lo Lao
    lt Lithuanian
    lv Latvian
    mg Malagasy
    mi Maori
    mk Macedonian
    ml Malayalam
    mn Mongolian
    mr Marathi
    ms Malay
    mt Maltese
    my Myanmar
    ne Nepali
    nl Dutch
    no Norwegian
    ny Nyanja
    or Oriya
    pa Punjabi
    pl Polish
    ps Pashto
    pt Portuguese
    ro Romanian
    ru Russian
    rw Kinyarwanda
    sd Sindhi
    si Sinhala
    sk Slovak
    sl Slovenian
    sm Samoan
    sn Shona
    so Somali
    sq Albanian
    sr Serbian
    st Sesotho
    su Sundanese
    sv Swedish
    sw Swahili
    ta Tamil
    te Telugu
    tg Tajik
    th Thai
    tk Turkmen
    tl Filipino
    tr Turkish
    tt Tatar
    ug Uighur
    uk Ukrainian
    ur Urdu
    uz Uzbek
    vi Vietnamese
    xh Xhosa
    yi Yiddish
    yo Yoruba
    zh Chinese Simplified
    zh-TW Chinese Traditional
    zu Zulu

    For more information, see the API documentation.

  • Dynamic Client Registration Support Added

    For decentralized applications, like open source CMSs WordPress and Ghost, we’ve added support for dynamic client registration, which allows developers to grant individual API keys to users with a user-friendly signup process.

    This or the use of a proxy is required for applications where a single API key can’t be shared between all installations due to the code being publicly distributed.

    Since this is not a typical use case, please reach out to the Unsplash Team to let us know about your use case and we will enable the ability for your application.

    For more information, see the API documentation on dynamic client registration.

  • User likes statistics deprecation

    The ‘likes’ data in the /users/:username/statistics response has been deprecated. The total value will be returning 0 going forward, with the entire fragment (i.e., including historical info) to be removed in the near future.

  • Deprecation of ordering by 'popular'

    We are deprecating the option to order photos by popular on all endpoints (e.g., GET /photos). While the functionality will still exist in the immediate future, it will be soon be removed.

  • Content filtering

    We’ve added a new section to the API documentation to publicly clarify our content safety guidelines:

    By default, endpoints set the content_filter to low, which guarantees that no content violating our submission guidelines (like images containing nudity or violence) will be returned in results.

    To give you flexibility in filtering content further, set the content_filter to high (on endpoints that support it) to further remove content that may be unsuitable for younger audiences. Note that we can’t guarantee that all potentially unsuitable content is removed.

    We’ve added support for content filtering to GET /search/photos and GET /random.

    param Description
    content_filter Limit results by content safety. (Optional; default: low). Valid values are low and high.

    Note: if you were previously using the experimental and undocumented safe boolean param, this has been deprecated and replaced by the content_filter param. safe=true corresponds to content_filter=high and safe=false corresponds to content_filter=low. We will be removing support for safe in a future update.

  • New filtering and ordering options

    GET /search/photos adds support for orientation, dominant color filtering, and relevancy vs latest ordering:

    param Description
    order_by How to sort the photos. (Optional; default: relevant). Valid values are latest and relevant.
    color Filter results by color. Valid values are: black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, and blue.
    orientation Filter search results by photo orientation. Valid values are landscape, portrait, and squarish.

    GET /collections/:id/photos adds support for orientation filtering:

    param Description
    orientation Filter collection results by photo orientation. Valid values are landscape, portrait, and squarish.

    GET /users/:username/photos adds support for orientation filtering:

    param Description
    orientation Filter a user’s photo results by photo orientation. Valid values are landscape, portrait, and squarish.

    GET /users/:username/likes adds support for orientation filtering:

    param Description
    orientation Filter a user’s likes by photo orientation. Valid values are landscape, portrait, and squarish.
  • Deprecated endpoint EOL: curated photos, old search, photo stats

    Three deprecated endpoints have been removed:

  • Curated Collections removal

    The deprecated Curated Collection endpoints have been removed. This includes:

    • GET /collections/curated
    • GET /collections/curated/:id
    • GET /collections/curated/:id/photos
  • 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