Showing preview only (210K chars total). Download the full file or copy to clipboard to get everything.
Repository: 500px/api-documentation
Branch: master
Commit: b1e82745e45f
Files: 51
Total size: 195.0 KB
Directory structure:
gitextract_xgnx4pl1/
├── .gitignore
├── .gitmodules
├── 500px-api.xml
├── README.md
├── authentication/
│ ├── POST_oauth_accesstoken.md
│ ├── POST_oauth_authorize.md
│ ├── POST_oauth_requesttoken.md
│ └── upload_key.md
├── basics/
│ ├── formats_and_terms.md
│ ├── terms_of_use.md
│ └── upload.md
├── endpoints/
│ ├── collections/
│ │ ├── DELETE_collections_id.md
│ │ ├── GET_collections.md
│ │ ├── GET_collections_id.md
│ │ ├── POST_collections.md
│ │ └── PUT_collections_id.md
│ ├── comments/
│ │ └── POST_comments_id_comments.md
│ ├── galleries/
│ │ ├── DELETE_galleries_id.md
│ │ ├── GET_galleries.md
│ │ ├── GET_galleries_id.md
│ │ ├── GET_galleries_id_items.md
│ │ ├── GET_galleries_id_share_url.md
│ │ ├── POST_galleries.md
│ │ ├── PUT_galleries_id.md
│ │ ├── PUT_galleries_id_items.md
│ │ └── PUT_galleries_reposition.md
│ ├── photo/
│ │ ├── DELETE_photos_id.md
│ │ ├── DELETE_photos_id_tags.md
│ │ ├── DELETE_photos_id_vote.md
│ │ ├── GET_photos.md
│ │ ├── GET_photos_id.md
│ │ ├── GET_photos_id_comments.md
│ │ ├── GET_photos_id_votes.md
│ │ ├── GET_photos_search.md
│ │ ├── POST_photos.md
│ │ ├── POST_photos_id_comments.md
│ │ ├── POST_photos_id_report.md
│ │ ├── POST_photos_id_tags.md
│ │ ├── POST_photos_id_vote.md
│ │ └── PUT_photos_id.md
│ ├── template.md
│ └── user/
│ ├── DELETE_users_id_friends.md
│ ├── GET_users.md
│ ├── GET_users_id_followers.md
│ ├── GET_users_id_friends.md
│ ├── GET_users_search.md
│ ├── GET_users_show.md
│ └── POST_users_id_friends.md
└── examples/
├── PHP/
│ └── PHP.md
├── Ruby/
│ └── xauth.rb
└── iOS/
└── API Tutorials.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .gitignore
================================================
.DS_Store
================================================
FILE: .gitmodules
================================================
[submodule "examples/python-sdk"]
path = examples/python-sdk
url = git@github.com:500px/PxMagic.git
[submodule "examples/android-sdk"]
path = examples/android-sdk
url = git@github.com:500px/500px-android-sdk.git
[submodule "examples/iOS-sdk"]
path = examples/iOS-sdk
url = git@github.com:500px/500px-iOS-api.git
[submodule "examples/TroubledPixels"]
path = examples/TroubledPixels
url = https://github.com/arthurnn/TroubledPixels
================================================
FILE: 500px-api.xml
================================================
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:apigee="http://api.apigee.com/wadl/2010/07/"
xmlns="http://wadl.dev.java.net/2009/02"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02 http://apigee.com/schemas/wadl-schema.xsd http://api.apigee.com/wadl/2010/07/ http://apigee.com/schemas/apigee-wadl-extensions.xsd">
<!-- Base defines the domain and base path of the endpoint -->
<resources base="https://api.500px.com/v1">
<resource path="photos">
<param name="feature" default="fresh_today" required="true">
<doc>
Photo stream.
</doc>
<option value="popular"/>
<option value="upcoming"/>
<option value="editors"/>
<option value="fresh_today"/>
<option value="fresh_yesterday"/>
<option value="fresh_week"/>
<option value="user" />
<option value="user_friends" />
</param>
<param name="user_id" type="xsd:string">
<doc>User ID 'user' Photo streeam</doc>
</param>
<param name="username" type="xsd:string">
<doc>OR username for 'user' Photo streeam</doc>
</param>
<param name="only" type="xsd:string">
<doc>String name of the category to return photos from</doc>
</param>
<param name="exclude" type="xsd:string">
<doc>String name of the category to exclude photos by.</doc>
</param>
<param name="sort" type="xsd:string">
<doc>
Sort photos in the specified order.
</doc>
<option value="created_at"/>
<option value="rating"/>
<option value="times_viewed"/>
<option value="votes_count"/>
<option value="comments_count"/>
<option value="taken_at" />
</param>
<param name="page" type="xsd:string">
<doc>Return a specific page in the photo stream. Page numbering is 1-based.</doc>
</param>
<param name="rpp" type="xsd:string">
<doc>The number of results to return. Can not be over 100, default 20.</doc>
</param>
<param name="image_size" default="3">
<doc>
The photo size to be returned.
</doc>
<option value="1"/>
<option value="2"/>
<option value="3"/>
<option value="4"/>
</param>
<param name="include_store">
<doc>
Returns market infomation about the photo.
</doc>
<option value="store_download"/>
<option value="store_print"/>
</param>
<param name="include_states">
<doc>
Returns state of the photo for the currently logged in user and authenticated request.
</doc>
<option value="voted"/>
<option value="purchased"/>
</param>
<param name="tags" type="xsd:string" style="query">
<doc>Returns an array of tags for the photo.</doc>
</param>
<method id="get_photos" name="GET" apigee:displayName="photos">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
<apigee:tag>Show</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<apigee:example url="/photos" />
<doc title="GET Photos" apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos.md">
Retrieves list of photos
</doc>
</method>
</resource>
<resource path="photos/search">
<param name="term" type="xsd:string">
<doc>A keyword to search for.</doc>
</param>
<param name="tag" type="xsd:string">
<doc>A complete tag string to search for.</doc>
</param>
<param name="page" type="xsd:integer">
<doc>Return a specific page. Page numbering is 1-based.</doc>
</param>
<param name="rpp" type="xsd:integer">
<doc>The number of results to return. Can not be over 100, default 20.</doc>
</param>
<param name="tags" type="xsd:string">
<doc>Returns an array of tags for each photo.</doc>
</param>
<method id="get_photos_search" name="GET" apigee:displayName="photos/search">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_search.md">
Returns a listing of twenty (up to one hundred) photos from search results for a specified tag or keyword.
</doc>
</method>
</resource>
<resource path="photos/{id}">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID</doc>
</param>
<param name="image_size" default="3">
<doc>
The photo size to be returned.
</doc>
<option value="1"/>
<option value="2"/>
<option value="3"/>
<option value="4"/>
</param>
<param name="comments">
<doc>Return comments to the photo in the response. Comments are returned in order of creation, 20 entries per page.</doc>
<option value="1"/>
<option value="2"/>
</param>
<param name="comments_page" type="xsd:integer">
<doc>Return the specified page from the comments listing. Page numbers are 1-based.</doc>
</param>
<param name="tags" type="xsd:string">
<doc>Returns an array of tags for the photo.</doc>
</param>
<method id="get_photos_id" name="GET" apigee:displayName="photos/{id}">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id.md">
Returns detailed information of a single photo.
</doc>
</method>
</resource>
<resource path="photos/{id}/comments">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID</doc>
</param>
<param name="page" type="xsd:integer">
<doc>Return a specific page in the comment listing. Page numbering is 1-based.</doc>
</param>
<method id="get_photos_id_comments" name="GET" apigee:displayName="photos/{id}/comments">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_comments.md">
Returns a listing of twenty comments for the photo.
</doc>
</method>
</resource>
<resource path="photos/{id}/votes">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID</doc>
</param>
<param name="page" type="xsd:integer">
<doc>Return a specific page in the comment listing. Page numbering is 1-based.</doc>
</param>
<param name="rpp" type="xsd:integer">
<doc>The number of results to return. Can not be over 100, default 20.</doc>
</param>
<method id="get_photos_id_votes" name="GET" apigee:displayName="photos/{id}/votes">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
<apigee:tag>Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<apigee:example url="/photos/{id}/votes" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_votes.md">
Likes the photo
</doc>
</method>
</resource>
<resource path="photos/{id}">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID</doc>
</param>
<param name="id" type="xsd:integer">
<doc>The Photo ID to update.</doc>
</param>
<param name="name" type="xsd:string">
<doc>Title for the photo.</doc>
</param>
<param name="description" type="xsd:string">
<doc>The description of the photo.</doc>
</param>
<method id="put_photos_id" name="PUT" apigee:displayName="photos/{id}">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
<apigee:tag>Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<apigee:example url="/photos/{id}" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/PUT_photos_id.md">
Updates a photo.
</doc>
</method>
</resource>
<resource path="photos">
<param name="name" type="xsd:string">
<doc>Title for the photo.</doc>
</param>
<param name="description" type="xsd:string">
<doc>The description of the photo.</doc>
</param>
<param name="category" type="xsd:integer">
<doc>A numerical ID for the Category of the photo</doc>
</param>
<!-- Photo technical details -->
<param name="shutter_speed" type="xsd:string">
<doc>Shutter speed in seconds, represented by string containing a rational expression if the value is 1sec.</doc>
</param>
<param name="focal_length" type="xsd:string">
<doc>Focal length in millimetres, a string representing an integer value</doc>
</param>
<param name="aperture" type="xsd:string">
<doc>Aperture value</doc>
</param>
<param name="iso" type="xsd:string">
<doc>ISO value</doc>
</param>
<param name="camera" type="xsd:string">
<doc>Make and model of the camera. Note: Please make sure it contains sensible information (eg., does not contain camera's make or model twice)</doc>
</param>
<param name="lens" type="xsd:string">
<doc>Lens used to make this photo</doc>
</param>
<!-- Geographical information of the photo: -->
<param name="latitude" type="xsd:string">
<doc>Latitude, in decimal format</doc>
</param>
<param name="longitude" type="xsd:string">
<doc>Longitude, in decimal format</doc>
</param>
<!-- Geographical information of the photo: -->
<param name="privacy" type="xsd:integer">
<doc> Whether to hide the photo from the user profile on the website. Otherwise, the photo is only available for use in galleries. Recognized values: 1, 0.</doc>
</param>
<method id="post_photos" name="POST" apigee:displayName="photos">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
<apigee:tag>Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<apigee:example url="/photos" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md">
Create a new photo on behalf of the user, and receive an upload key in exchange.
</doc>
</method>
</resource>
<resource path="photos/{id}/vote">
<param name="id" type="xsd:string" required="true">
<doc> ID of the photo the vote is cast upon.</doc>
</param>
<param name="vote" default="1">
<doc>
vote, values: '0' for 'dislike' or '1' for 'like'.
</doc>
<option value="0"/>
<option value="1"/>
</param>
<method id="post_photos_id_vote" name="POST" apigee:displayName="photos/{id}/vote">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true"/>
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_vote.md">
Allows the user to vote for a photo.
</doc>
</method>
</resource>
<resource path="photos/{id}/tags">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID to add tags for.</doc>
</param>
<param name="tags" type="xsd:string">
<doc>Coma separated tags.</doc>
</param>
<method id="post_photos_id_tags" name="POST" apigee:displayName="photos/{id}/tags">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true"/>
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_tags.md">
Adds tags to the photo. Accepts one or multiple coma separated tags.
</doc>
</method>
</resource>
<resource path="photos/{id}/comments">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID to post comments for.</doc>
</param>
<param name="body" type="xsd:string">
<doc>Content of the comment.</doc>
</param>
<method id="post_photos_id_comments" name="POST" apigee:displayName="photos/{id}/comments">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true"/>
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_comments.md">
Creates a new comment for the photo.
</doc>
</method>
</resource>
<resource path="photos/{id}">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID to delete.</doc>
</param>
<method id="delete_photos_id" name="DELETE" apigee:displayName="photos/{id}">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id.md">
Deletes the photo from the User's library.
</doc>
</method>
</resource>
<resource path="photos/{id}/tags">
<param name="id" type="xsd:string" required="true">
<doc>The Photo ID to remove tags from.</doc>
</param>
<param name="tags" type="xsd:string">
<doc>Coma separated tags.</doc>
</param>
<method id="delete_photos_id_tags" name="DELETE" apigee:displayName="photos/{id}/tags">
<apigee:tags>
<apigee:tag primary="true">Photos</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id_tags.md">
Removes tags from the photo. Accepts one or multiple coma separated tags.
</doc>
</method>
</resource>
<!-- UPLOAD -->
<resource path="upload">
<param name="photo_id" type="xsd:string" required="true">
<doc>The ID of the photo the file is being uploaded for. The ID should be known to the client from the POST photos request result.</doc>
</param>
<param name="upload_key" type="xsd:string" required="true">
<doc>Upload key</doc>
</param>
<param name="consumer_key" type="xsd:string" required="true">
<doc>Your application Consumer key.</doc>
</param>
<param name="access_key" type="xsd:string" required="true">
<doc>Oauth token.</doc>
</param>
<param name="file" type="xsd:string" required="true">
<doc>The multipart HTTP upload. This is expected to be of the same format as when a file is being sent from an HTML file form.</doc>
</param>
<method id="upload" name="POST" apigee:displayName="upload">
<apigee:tags>
<apigee:tag primary="true">Upload</apigee:tag>
</apigee:tags>
<apigee:authentication required="false" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/upload/POST_upload.md">
Allows an application to upload the photo file.
Warning: This endpoint cannot accept oauth signed requests.
</doc>
</method>
</resource>
<resource path="photos/upload">
<param name="file" type="xsd:string" required="true">
<doc>The multipart HTTP upload. This is expected to be of the same format as when a file is being sent from an HTML file form.</doc>
</param>
<!-- optional params -->
<param name="name" type="xsd:string">
<doc>Title for the photo.</doc>
</param>
<param name="description" type="xsd:string">
<doc>The description of the photo.</doc>
</param>
<param name="category" type="xsd:integer">
<doc>A numerical ID for the Category of the photo</doc>
</param>
<param name="privacy" type="xsd:integer" default="0">
<doc>Whether to hide the photo from the user profile on the website. Otherwise, the photo is only available for use in Collections/Portfolio. 0 - Public, 1 - Private</doc>
<option value="0"/>
<option value="1"/>
</param>
<!-- Photo technical details -->
<param name="shutter_speed" type="xsd:string">
<doc>Shutter speed in seconds, represented by string containing a rational expression if the value is 1sec.</doc>
</param>
<param name="focal_length" type="xsd:string">
<doc>Focal length in millimetres, a string representing an integer value</doc>
</param>
<param name="aperture" type="xsd:string">
<doc>Aperture value</doc>
</param>
<param name="iso" type="xsd:string">
<doc>ISO value</doc>
</param>
<param name="camera" type="xsd:string">
<doc>Make and model of the camera. Note: Please make sure it contains sensible information (eg., does not contain camera's make or model twice)</doc>
</param>
<param name="lens" type="xsd:string">
<doc>Lens used to make this photo</doc>
</param>
<!-- Geographical information of the photo: -->
<param name="latitude" type="xsd:string">
<doc>Latitude, in decimal format</doc>
</param>
<param name="longitude" type="xsd:string">
<doc>Longitude, in decimal format</doc>
</param>
<method id="photos_upload" name="POST" apigee:displayName="(NEW) photos/upload">
<apigee:tags>
<apigee:tag primary="true">Upload</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc>
(This is a new, simplified upload endpoint.) Allows an application to upload the photo.
</doc>
</method>
</resource>
<!-- //end UPLOAD -->
<!-- USER -->
<resource path="users">
<method id="get_users" name="GET" apigee:displayName="users">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users.md">
Returns the profile information for the current user.
</doc>
</method>
</resource>
<resource path="users/show">
<param name="id" type="xsd:string">
<doc>
Return information for the specified user ID.
</doc>
</param>
<param name="username" type="xsd:string">
<doc>Return information for the user with the specified username.</doc>
</param>
<param name="email" type="xsd:string">
<doc>Return information for the user with the specified email address.</doc>
</param>
<method id="get_users_show" name="GET" apigee:displayName="users/show">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_show.md">
Returns the profile information for a specified user.
</doc>
</method>
</resource>
<resource path="users/{id}/friends">
<param name="id" type="xsd:string" required="true">
<doc>Return information for the specified user ID</doc>
</param>
<param name="page" type="xsd:string">
<doc>Return the specified page of the resource. Page numbering is 1-based.</doc>
</param>
<param name="rpp" type="xsd:string">
<doc>Results Per Page, default 20, max 100.</doc>
</param>
<method id="get_users_id_friends" name="GET" apigee:displayName="users/{id}/friends">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_friends.md">
Returns a list of friends for the specified user.
</doc>
</method>
</resource>
<resource path="users/{id}/followers">
<param name="id" type="xsd:string" required="true">
<doc>ID of the user.</doc>
</param>
<param name="page" type="xsd:string">
<doc>Return the specified page of the resource. Page numbering is 1-based.</doc>
</param>
<method id="get_users_id_followers" name="GET" apigee:displayName="users/{id}/followers">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_followers.md">
Returns a list of users who follow the specified user.
</doc>
</method>
</resource>
<resource path="users/search">
<param name="term" type="xsd:string" required="true">
<doc>A keyword to search for.</doc>
</param>
<param name="page" type="xsd:string">
<doc>Return the specified page of the resource. Page numbering is 1-based.</doc>
</param>
<param name="rpp" type="xsd:string">
<doc>Results Per Page, default 20, max 100.</doc>
</param>
<method id="get_users_search" name="GET" apigee:displayName="users/search">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_search.md">
Return listing of ten (up to one hundred) users from search results for a specified search term.
</doc>
</method>
</resource>
<resource path="users/{id}/friends">
<param name="id" type="xsd:string" required="true">
<doc> ID of the User to add to the followers list.</doc>
</param>
<method id="post_users_search" name="POST" apigee:displayName="users/{id}/friends">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/POST_users_id_friends.md">
Add the user to the list of followers.
</doc>
</method>
</resource>
<resource path="users/{id}/friends">
<param name="id" type="xsd:string" required="true">
<doc>ID of the User to remove from the followers list.</doc>
</param>
<method id="delete_users_search" name="DELETE" apigee:displayName="users/{id}/friends">
<apigee:tags>
<apigee:tag primary="true">User</apigee:tag>
</apigee:tags>
<apigee:authentication required="true" />
<doc apigee:url="https://github.com/500px/api-documentation/blob/master/endpoints/user/DELETE_users_id_friends.md">
Removes the user from the list of followers.
</doc>
</method>
</resource>
<!-- //end USERS -->
</resources>
</application>
================================================
FILE: README.md
================================================
# 500px API
500px API provides programmatic access to 500px functionality and content.
Version 1 of the API is limited to the essentials of the website's functionality: viewing feature streams, photo information and comments, as well as user profiles.
The API is [REST API](http://en.wikipedia.org/wiki/Representational_State_Transfer "RESTful")
and uses [OAuth](http://oauth.net/ "OAuth") 1.0a for user authentication purposes.
Currently, return format for all endpoints is [JSON](http://json.org/ "JSON").
You can try our API in [console](http://bitly.com/api500px) ([http://bitly.com/api500px](http://bitly.com/api500px))
See [status.500px.com](http://status.500px.com) for API status updates, outages, and scheduled maintenance.
***
## Basics
- **[Formats and Terms](https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md)**
- **[API Terms of Use](https://github.com/500px/api-documentation/blob/master/basics/terms_of_use.md)**
- **[Uploading photos](https://github.com/500px/api-documentation/blob/master/basics/upload.md)**
## Examples
- **[JavaScript](http://500px.github.com/500px-js-sdk)**
- **[iOS](https://github.com/500px/api-documentation/blob/master/examples/iOS/API%20Tutorials.md)**
- **[Ruby](https://github.com/500px/api-documentation/blob/master/examples/Ruby/)**
- **[PHP](https://github.com/500px/api-documentation/blob/master/examples/PHP/PHP.md)**
## Changes
* 2017-12-12 Deprecated the old upload flow with `upload_key` and [replaced with new one](https://github.com/500px/api-documentation/blob/master/basics/upload.md)
* 2014-03-27 Deprecated photo object's image_url key.
## SDK
- **[JavaScript](https://github.com/500px/500px-js-sdk)**
- **[Android](https://github.com/500px/500px-android-sdk)**
- **[iOS](https://github.com/500px/500px-iOS-api)**
## Endpoints
#### Photo Resources
- **[<code>GET</code> photos](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos.md)**
- **[<code>GET</code> photos/search](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_search.md)**
- **[<code>GET</code> photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id.md)**
- **[<code>GET</code> photos/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_comments.md)**
- **[<code>GET</code> photos/:id/votes](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_votes.md)**
- **[<code>PUT</code> photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/PUT_photos_id.md)**
- **[<code>POST</code> photos](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md)**
- **[<code>POST</code> photos/:id/vote](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_vote.md)**
- **[<code>DELETE</code> photos/:id/vote](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id_vote.md)**
- **[<code>POST</code> photos/:id/tags](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_tags.md)**
- **[<code>POST</code> photos/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_comments.md)**
- **[<code>POST</code> photos/:id/report](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_report.md)**
- **[<code>DELETE</code> photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id.md)**
- **[<code>DELETE</code> photos/:id/tags](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id_tags.md)**
#### User Resources
- **[<code>GET</code> users](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users.md)**
- **[<code>GET</code> users/show](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_show.md)**
- **[<code>GET</code> users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_friends.md)**
- **[<code>GET</code> users/:id/followers](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_followers.md)**
- **[<code>GET</code> users/search](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_search.md)**
- **[<code>POST</code> users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/POST_users_id_friends.md)**
- **[<code>DELETE</code> users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/DELETE_users_id_friends.md)**
#### Gallery Resources
- **[<code>GET</code> users/:user_id/galleries](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries.md)**
- **[<code>GET</code> users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md)**
- **[<code>GET</code> users/:user_id/galleries/:id/items](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id_items.md)**
- **[<code>GET</code> users/:user_id/galleries/:id/share_url](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md)**
- **[<code>PUT</code> users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id.md)**
- **[<code>PUT</code> users/:user_id/galleries/:id/items](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id_items.md)**
- **[<code>PUT</code> users/:user_id/galleries/reposition](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_reposition.md)**
- **[<code>POST</code> users/:user_id/galleries](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/POST_galleries.md)**
- **[<code>DELETE</code> users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/DELETE_galleries_id.md)**
#### Collections/Sets Resources
- **DEPRECATED**. Please use [Gallery Resources](#gallery-resources) instead
#### Comment Resources
- **[<code>POST</code> comments/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/comments/POST_comments_id_comments.md)**
## Directory API
You can also programmatically access the [500px Directory](https://500px.com/directory). The Directory allows you to contact photographers and search for photographers by speciality, availability, service rates, language, camera, and other information. To gain access to the Directory API please contact sales@500px.com.
## Authentication
- **[<code>POST</code> oauth/request_token](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md)**
- **[<code>POST</code> oauth/authorize](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_authorize.md)**
- **[<code>POST</code> oauth/access_token](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_accesstoken.md)**
- **[Upload key](https://github.com/500px/api-documentation/blob/master/authentication/upload_key.md)**
## FAQ
### What do I need to know before I start using the API?
Got rust on your skills? No worries. Here are the docs you might need to get started:
- HTTPS protocol
- [REST software pattern][]
- Authentication with [OAuth][] (or the official [Beginner’s Guide][])
- Data serialization with [JSON][] (or see a [quick tutorial][])
### How do I connect to the 500px.com API?
The API is only available to authenticated clients. Clients should authenticate users using [OAuth][]. Once authenticated, you need to request a resource from one of the endpoints using HTTPS. Generally, reading any data is done through a request with GET method. If you want our server to create, update or delete a given resource, POST or PUT methods are required.
### What return formats do you support?
500px API currently returns data in [JSON](http://json.org/ "JSON") format.
### What kind of authentication is required?
Applications must identify themselves to access any resource.
If your application only needs read-only access and does not authenticate the user, **consumer_key** containing a valid Consumer Key parameter should be specified in the query string. Otherwise, [OAuth](https://github.com/500px/api-documentation/tree/master/authentication) or upload key authentication takes care of identifying the application as well as the user accessing the API.
### Is there a request rate limit?
There is a rate limit of 1,000,000 API requests per month per account. We will contact you and, if required, disable your application if we find that your application is exceeding this limit or interfering with our system's stability. This revised rate limit came into effect May 1, 2014.
[REST software pattern]: http://en.wikipedia.org/wiki/Representational_State_Transfer
[OAuth]: http://oauth.net/core/1.0a/
[Beginner’s Guide]: http://hueniverse.com/oauth/
[JSON]: http://json.org
[quick tutorial]: http://www.webmonkey.com/2010/02/get_started_with_json/
[Register your application]: http://500px.com/settings/applications
[API Terms of Use]: https://github.com/500px/api-documentation/blob/master/basics/terms_of_use.md
[See if the concepts used by the API are familiar to you]: https://github.com/500px/api-documentation#what-do-i-need-to-know-before-i-start-using-the-api
================================================
FILE: authentication/POST_oauth_accesstoken.md
================================================
# OAuth
POST oauth/access_token
## Description
Allows a Consumer application to exchange an OAuth Request Token for an OAuth Access Token, which can be used to access protected resources on behalf of the user. This method fulfills [Section 6.3][] of the [OAuth 1.0 authentication flow][].
The OAuth Access Token may also be used for xAuth operations.
***
## Requires authentication
OAuth Request Token received using the [request_token][] method. Requires oauth_verifier when using [authorize](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_authorize.modificator) in authentication workflow.
Note that this request must be signed with a Request Token even when using the xAuth workflow.
***
## Parameters
Standard oAuth workflow:
- **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request.
xAuth workflow:
- **x_auth_mode** _(required)_ — xAuth modificator. Recognized values: 'client_auth'.
- **x_auth_username** _(required)_ — The username or email address of the user to obtain a token for.
- **x_auth_password** _(required)_ — The password of the user for which to obtain a token for.
***
## Return format
Text, containing an query string-encoded list of OAuth parameters.
- **oauth_token** — An Access Token
- **oauth_token_secret** — An Access Token's Secret
***
## Errors
- **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
[Section 6.3]: http://oauth.net/core/1.0/#auth_step3
[OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
[request_token]: https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md
================================================
FILE: authentication/POST_oauth_authorize.md
================================================
# OAuth
POST oauth/authorize
## Description
Allows a Consumer application to obtain user authorization for an OAuth Request Token. This method fulfills [Section 6.2][] of the [OAuth 1.0 authentication flow][]. The method will use the currently logged in user as the account for access authorization and will request the user to log in if they have no active session with 500px.com.
***
## Requires authentication
OAuth Request Token received using [request_token][] method.
***
## Parameters
A valid OAuth request should be issued. You can provide parameters in Authorization HTTP-headers, query string, or body of the request. If you're using HTTP-header based OAuth, you shouldn't include <code>oauth_*</code> parameters in the POST body or query string.
- **oauth_token** _(required)_ — A Request Token received from [request_token][] method
- **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request
***
## Return format
The user will be redirected to oauth_callback URL once they authorize the request. The request will contain two parameters:
- **oauth_token** — A Request Token issued by the Provider at the [request_token][] step
- **oauth_verifier** — The OAuth Verifier is a verification code tied to the Request Token. The OAuth Verifier and Request Token both must be provided in exchange for an Access Token.
***
## Errors
- **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
[Section 6.2]: http://oauth.net/core/1.0/#auth_step2
[OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
[request_token]: https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md
================================================
FILE: authentication/POST_oauth_requesttoken.md
================================================
# OAuth
POST oauth/request_token
## Description
Allows a Consumer application to obtain an OAuth Request Token to request user authorization. This method fulfills [Section 6.1][] of the [OAuth 1.0 authentication flow][].
***
## Requires authentication
False
***
## Parameters
A valid OAuth request should be issued. You can provide parameters in Authorization HTTP-headers, query string, or body of the request. If you're using HTTP-header based OAuth, you shouldn't include oauth_* parameters in the POST body or query string.
- **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request.
***
## Return format
Text, containing an query string-encoded list of OAuth parameters.
- **oauth_token** — A Request Token
- **oauth_token_secret** — A Request Token's Secret
***
## Errors
- **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
[Section 6.1]: http://oauth.net/core/1.0/#auth_step1
[OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
================================================
FILE: authentication/upload_key.md
================================================
# Upload key authorization
OAuth does not support encoding multipart/form-data messages. As such, it is impossible to send a valid OAuth request containing file data without performing extra encoding. As a workaround, 500px.com API uses a separate request authentication schema for file uploads.
***
## Authentication requirements
The party making the request is still required to obtain an OAuth Access Token through standard OAuth workflow, and must include OAuth consumer key and access token key in the request. Current upload authentication also requires obtaining an photo_id and upload_key values returned in response to a [POST photos][] request.
## Parameters
To have an upload request authenticate successfully, the following parameters must be included:
## Return format
Text, containing an query string-encoded list of OAuth parameters.
- **consumer_key** — OAuth Consumer key of the application sending the request
- **access_key** — An authorized OAuth Access Token received during the standard OAuth workflow
- **upload_key** — Upload key received in the response to a [POST photos][] request
- **photo_id** — The ID of the photo the file is being uploaded for
[POST photos]: https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md
================================================
FILE: basics/formats_and_terms.md
================================================
# Formats and Terms
[500px.com][] allows discovery of the photography uploaded by users in a
number of ways. An essential part of presentation is photo streams.
Accessing the following streams is possible though means of the API:
[500px.com]: http://500px.com/
***
## 500px Photo Terms
### Rating-based streams
- [Popular][], photos with a rating over 80, sorted by rating, cached for 5 minutes
- [Upcoming][], photos with a rating over 70, sorted by creation timestamp, cached for 5 minutes
### Time-based (Fresh) streams:
- [Today][], photos created since midnight (EST time), cached for 60 seconds
- [Yesterday][], photos created between last day’s midnight and past midnight (EST time), cached until the end of hour
- [Week][], photos created in the past 7 days, excluding today, cached until the end of hour
### User-based streams:
- [User’s Photos][], all active public photos of a given user
- [User’s Friends’ Photos][Week], a collection of User’s Photos streams from all followings of a given user
### Special streams:
- [Editors’ Choice][], photos selected by 500px.com Editors, cached indefinitely
[Popular]: http://500px.com/popular
[Upcoming]: http://500px.com/upcoming
[Today]: http://500px.com/fresh/today
[Yesterday]: http://500px.com/fresh/yesterday
[Week]: http://500px.com/fresh/week
[User’s Photos]: http://500px.com/iansobolev
[Editors’ Choice]: http://500px.com/editors
***
## Image URLs and Image Sizes
You'll find the URLs to the image(s) for a photo in the `images` field in the returned JSON for a photo. The images provided with our standard API access will be watermarked with the 500px logo and attribution. For non-watermarked images please contact sales@500px.com
**Important** - You must not alter the URLs returned by the API in any way. Altered URLs will be rejected by our system when the image is loaded. Instead, please use the `image_size` parameter to request the sizes your application needs.
500px has a number of preset image sizes. Most API requests that return image URLs can be instructed to return the URLs for one or more specific sizes. To retrieve the URL for a specific image size, include that size's ID in the query string of the request, using the `image_size` parameter:
```
GET /v1/photos?feature=popular&image_size=3
```
If you want to request multiple sizes, you can pass an array for `image_size` as well:
```
GET /v1/photos?feature=popular&image_size[]=3&image_size[]=2
```
which can equivalently be specified as:
```
GET /v1/photos?feature=popular&image_size=3,2
```
These are the standard cropped sizes:
<table id="image_sizes">
<tr>
<th>ID</th>
<th>Dimensions</th>
</tr>
<tr><td>1</td><td>70px x 70px</td></tr>
<tr><td>2</td><td>140px x 140px</td></tr>
<tr><td>3</td><td>280px x 280px</td></tr>
<tr><td>100</td><td>100px x 100px</td></tr>
<tr><td>200</td><td>200px x 200px</td></tr>
<tr><td>440</td><td>440px x 440px</td></tr>
<tr><td>600</td><td>600px x 600px</td></tr>
</table>
These are the standard uncropped sizes:
<table id="image_sizes">
<tr>
<th>ID</th>
<th>Dimensions</th>
</tr>
<tr><td>4</td><td>900px on the longest edge</td></tr>
<tr><td>5</td><td>1170px on the longest edge</td></tr>
<tr><td>6</td><td>1080px high</td></tr>
<tr><td>20</td><td>300px high</td></tr>
<tr><td>21</td><td>600px high</td></tr>
<tr><td>30</td><td>256px on the longest edge</td></tr>
<tr><td>31</td><td>450px high</td></tr>
<tr><td>1080</td><td>1080px on the longest edge</td></tr>
<tr><td>1600</td><td>1600px on the longest edge</td></tr>
<tr><td>2048</td><td>2048px on the longest edge</td></tr>
</table>
***
## Categories
Categories of photos may be specified by their ID or string name, depending on the API method.
<table id="categories">
<tr>
<th>ID</th>
<th>Category</th>
</tr>
<tr><td>0</td><td>Uncategorized</td></tr>
<tr><td>10</td><td>Abstract</td></tr>
<tr><td>29</td><td>Aerial <sup>New!</sup></td></tr>
<tr><td>11</td><td>Animals</td></tr>
<tr><td>5</td><td>Black and White</td></tr>
<tr><td>1</td><td>Celebrities</td></tr>
<tr><td>9</td><td>City and Architecture</td></tr>
<tr><td>15</td><td>Commercial</td></tr>
<tr><td>16</td><td>Concert</td></tr>
<tr><td>20</td><td>Family</td></tr>
<tr><td>14</td><td>Fashion</td></tr>
<tr><td>2</td><td>Film</td></tr>
<tr><td>24</td><td>Fine Art</td></tr>
<tr><td>23</td><td>Food</td></tr>
<tr><td>3</td><td>Journalism</td></tr>
<tr><td>8</td><td>Landscapes</td></tr>
<tr><td>12</td><td>Macro</td></tr>
<tr><td>18</td><td>Nature</td></tr>
<tr><td>30</td><td>Night <sup>New!</sup></td></tr>
<tr><td>4</td><td>Nude</td></tr>
<tr><td>7</td><td>People</td></tr>
<tr><td>19</td><td>Performing Arts</td></tr>
<tr><td>17</td><td>Sport</td></tr>
<tr><td>6</td><td>Still Life</td></tr>
<tr><td>21</td><td>Street</td></tr>
<tr><td>26</td><td>Transportation <sup>New!</sup></td></tr>
<tr><td>13</td><td>Travel</td></tr>
<tr><td>22</td><td>Underwater</td></tr>
<tr><td>27</td><td>Urban Exploration <sup>New!</sup></td></tr>
<tr><td>25</td><td>Wedding <sup>New!</sup></td></tr>
</table>
## License Types
500px currently supports these types of licenses, more details can be found at http://500px.com/creativecommons
<table id="license_types">
<tr>
<th>ID</th>
<th>License Type</th>
</tr>
<tr><td>0</td><td>Standard 500px License</td></tr>
<tr><td>1</td><td>Creative Commons License Non Commercial Attribution</td></tr>
<tr><td>2</td><td>Creative Commons License Non Commercial No Derivatives</td></tr>
<tr><td>3</td><td>Creative Commons License Non Commercial Share Alike</td></tr>
<tr><td>4</td><td>Creative Commons License Attribution</td></tr>
<tr><td>5</td><td>Creative Commons License No Derivatives</td></tr>
<tr><td>6</td><td>Creative Commons License Share Alike</td></tr>
<tr><td>7</td><td>Creative Commons License Public Domain Mark 1.0</td></tr>
<tr><td>8</td><td>Creative Commons License Public Domain Dedication</td></tr>
</table>
## Gallery kinds
<table id="gallery_kinds">
<tr>
<th>ID</th>
<th>Gallery Kinds</th>
<th>Contents</th>
</tr>
<tr><td>0</td><td>General</td><td>Any photo on 500px</td></tr>
<tr><td>1</td><td>Lightbox</td><td>Marketplace photos</td></tr>
<tr><td>3</td><td>Portfolio<sup>*</sup></td><td>Photos displayed on the portfolio page</td></tr>
<tr><td>4</td><td>Profile<sup>*</sup></td><td>Photos uploaded by the gallery owner</td></tr>
<tr><td>5</td><td>Favorite</td><td>Photos favorited by the gallery owner via the old API.</td></tr>
</table>
<sub>* Can only contain photos uploaded by the gallery owner</sub>
## Photo object formats
Categories of photos may be specified by their ID or string name, depending on the API method.
### Short format
The short format of a Photo object includes the following data:
- **id** — ID of the photo, integer
- **name** — Title of the photo, string
- **description** — Description of the photo, string
- **camera** — Make and model of the camera this photo was made with, string
- **lens** — This photo’s camera lens information, string
- **focal\_length** — Focal length of the shot, string
- **iso** — ISO value of the shot, string
- **shutter\_speed** — Shutter speed value of the shot, string
- **aperture** — Aperture value of the shot, string
- **times\_viewed** - The number of views this photo has, integer
- **rating** — Rating of the photo, decimal
- **status** — Status of the photo in the system, integer. An active photo always has the status of 1.
- **created\_at** — Timestamp indicating time of photo creation, timestamp
- **category** — [Category][] of the photo, (short) integer
- **location** — A human-readable name of the location where the photo was taken, string
- **privacy** - Boolean value whether or not the community page (http://500px.com/photo/:id) of this photo is available. A value of true means the page is not available.
- **latitude** — Latitude of the location where the photo was taken, decimal
- **longitude** — Longitude of the location where the photo was taken, decimal
- **taken\_at** — Timestamp of when the photo was taken, timestamp
- **for\_sale** - Boolean value whether or not the photo is for sale
- **width** - The width of the original, unresized photo, integer
- **height** - The height of the origin, unresized photo, integer
- **votes\_count** — Number of votes cast on this photo, integer
- **comments\_count** — Number of comments this photo has, integer
- **nsfw** - Boolean value whether the current photo is NSFW
- **sales_count** - The number of sales this photo has
- **highest_rating** - The highest rating this photo has had, decimal
- **highest_rating_date** - The date the highest rating was reached on, timestamp
- **license_type** - [License type][] of the photo, (short) integer
- **converted** - Boolean value indicating whether or not this photo has been converted, **deprecated**.
- **image\_url** — URL of the image, string, **deprecated**
- **images** - Array with images URL and sizes
- **user** — Author’s profile in [short format][], object
- **galleries_count** - Number of galleries this photo is present in, integer
[Category]: #categories
[License type]: #license_types
### Full format
The full format of a Photo object includes the following data:
- **id** — ID of the photo, integer
- **name** — Title of the photo, string
- **description** — Description of the photo, string
- **camera** — Make and model of the camera this photo was made with, string
- **lens** — This photo’s camera lens information, string
- **focal\_length** — Focal length of the shot, string
- **iso** — ISO value of the shot, string
- **shutter\_speed** — Shutter speed value of the shot, string
- **aperture** — Aperture value of the shot, string
- **times\_viewed** - The number of views this photo has, integer
- **rating** — Rating of the photo, decimal
- **status** — Status of the photo in the system, integer. An active photo always has the status of 1.
- **created\_at** — Timestamp indicating time of photo creation, timestamp
- **category** — [Category][] of the photo, (short) integer
- **location** — A human-readable name of the location where the photo was taken, string
- **privacy** - Boolean value whether or not the community page (http://500px.com/photo/:id) of this photo is available. A value of true means the page is not available.
- **latitude** — Latitude of the location where the photo was taken, decimal
- **longitude** — Longitude of the location where the photo was taken, decimal
- **taken\_at** — Timestamp of when the photo was taken, timestamp
- **for\_sale** - Boolean value whether or not the photo is for sale
- **width** - The width of the original, unresized photo, integer
- **height** - The height of the origin, unresized photo, integer
- **votes\_count** — Number of votes cast on this photo, integer
- **comments\_count** — Number of comments this photo has, integer
- **nsfw** - Boolean value whether the current photo is NSFW
- **sales_count** - The number of sales this photo has
- **highest_rating** - The highest rating this photo has had, decimal
- **highest_rating_date** - The date the highest rating was reached on, timestamp
- **license_type** - [License type][] of the photo, (short) integer
- **converted** - Boolean value indicating whether or not this photo has been converted, **deprecated**.
- **image\_url** — URL of the image, string, **deprecated**
- **images** - Array with images URL and sizes
- **user** — Author’s profile in [short format][], object
- **comments** - If requested, an array of comments.
- **store_download** - Boolean value indicating whether or not the photo is for sale as a digital download.
- **store_print** - Boolean value indicating whether or not the photo is for sale as a canvas print.
- **editors_choice** - Boolean value indicating whether or not the photo is in Editors' Choice.
- **feature** - The section of the site this photo appears under, string. Possible values are popular upcoming fresh_today fresh_yesterday fresh_week
- **galleries_count** - Number of galleries this photo is present in, integer
If you are authenticated when making the request. These additional fields will be returned:
- **voted** — Boolean value whether the current user has voted for this photo
- **purchased** — Boolean value whether the current user has bought this photo
***
## User object formats
### Short format
The short format of a User object includes the following data:
- **id** — ID of the user, integer
- **username** — Username, string
- **firstname** — First name, string
- **lastname** — Last name, string
- **fullname** — A combination of first and last names or a username that would naturally appear on the site, string
- **city** — City as specified in user's profile, string
- **country** — Country as specified in user's profile, string
- **userpic\_url** — Profile picture’s URL of the user, string
- **upgrade\_status** — Whether the user is a premium user, integer. Non-zero values identify premium users; a value of 2 identifies an Awesome user while a value of 1 identifies a Plus user. Other states may be added in the future, so write your parsers accordingly.
- **followers_count** — User followers count
- **affection** — Affection value, integer.
### Profile format
The profile format of a User object includes the following data:
- **id** — ID of the user, integer
- **username** — Username, string
- **firstname** — First name, string
- **lastname** — Last name, string
- **fullname** — A combination of first and last names or a username that would naturally appear on the site, string
- **sex** — Sex of the user, string. Values: 1 and 2 for male and female respectively, 0 if user refused to specify their sex.
- **city** — City as specified in user’s profile, string
- **state** — State as specified in user’s profile, string
- **country** — Country as specified in user’s profile, string
- **active** — Active status of user. Values: 0 - not active, 1 - active, 2 - deleted by user, 3 - banned
- **registration\_date** — Registration timestamp, timestamp
- **about** — User’s about text, timestamp
- **domain** - The host name of the user's portfolio, string
- **locale** — User’s preferred locale, string. Current values: <code>en, ru, de, ja, br, es</code>.
- **upgrade\_status** — Whether the user is a premium user, integer. Non-zero values identify premium users; a value of 2 identifies an Awesome user while a value of 1 identifies a Plus user. Other states may be added in the future, so write your parsers accordingly.
- **upgrade\_type** - Whether this is a paid user or trial user. Values: 0 - free user, 1 - trial user, 2 - paid user
- **show\_nude** — Whether the user has content filter disabled, boolean.
- **userpic\_url** — Profile picture’s URL of the user, string
- **store\_on** - Whether the user has the store option enabled, boolean
- **contacts** — A dictionary of user’s contacts, object. Keys should be treated as provider names, and values as user IDs with given provider.
- **equipment** - A dictionary of a user's equipment. Possible keys are <code>camera, lens, misc</code>. Each key will have an array of values.
- **photos\_count** — Number of active photos posted by the user, integer.
- **galleries\_count** — Number of galleries visible on the user's profile, integer.
- **affection** — Affection value, integer.
- **friends\_count** — Number of people this user follows, integer.
- **followers\_count** — Number of people this user is being followed by, integer.
- **admin** - Boolean value that will be 1 if the user is a 500px team member.
- **avatars** - A dictionary of different avatar sizes. Keys are <code>default, large, small, tiny</code>. default is up to 300x300px, large is 100x100px, small is 50x50px, tiny is 30x30px.
If the user you are requesting is the currently authenticated user these additional fields will be returned:
- **email** - The user's email address.
- **upload\_limit** - The remaining upload limit this user has, integer
- **upload\_limit\_expiry** - The date at which additional uploads will be available, if the user is currently allowed to upload then this will be now, timestamp
- **upgrade\_expiry\_date** - The date at which the user's subscription will expire, timestamp
- **auth** - A dictionary of a user's social network authentications. Possible keys are <code>facebook, twitter, google_oauth2</code>. Each key will have a value of '1' as existing authentication or '0' as no authentication.
If you are authenticated these additional fields will be returned:
- **following** - A boolean value indicating whether or not you are following this user.
***
## Comment object formats
The profile format of a User object includes the following data:
### Full format
The full format of a Comment object includes the following data:
- **id** — ID of the comment, integer
- **body** — Content of the comment, string
- **to_whom_user_id** — To which user the comment was made, string
- **user_id** — User ID of author of the comment, string
- **created_at** — Timestamp indicating time the comment was created, timestamp
- **user** — Author's profile in [short format][], object
- **parent_id** - The ID of the comment that was replied to. If this value is null then the comment was not a reply to another comment, integer
- **flagged** - A boolean value indicating whether or not this comment was flagged for review.
- **rating** - The sum of the number of votes this comment has received, integer
If you are authenticated these additional attributes will be returned:
- **voted** - A boolean value indicating whether or not the currently authenticated user has voted on this comment.
***
## Gallery object formats
### Short format
The short format of a Gallery object includes the following data:
- **id** — ID of the gallery, integer
- **user_id** — ID of the user that owns the gallery, integer
- **name** — Title of the gallery, string
- **description** — Description of the gallery, string
- **subtitle** — A short (500 char.) blurb of the gallery, string
- **items_count** — Number of items in the gallery, integer
- **privacy** - Boolean value whether or not the gallery is private. A value of true means the gallery is private to the user
- **kind** - Indicates the **[gallery kind][]**, integer
- **created\_at** — Timestamp indicating time the gallery was created, timestamp
- **updated\_at** — Timestamp indicating time the gallery was updated, timestamp
- **cover_photo** - Array containing a JSON hash of the cover photo's id, size, url, and nsfw flag
- **custom_path** - Custom path of the gallery, string
- **last_added_photo** _(optional)_ - Photo that was last added to the gallery, in **[short format](https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format)**
- **user** _(optional)_ - User who owns the gallery, in **[short format][]**
### Full format
The full format of a Gallery object includes the following data:
- **id** — ID of the gallery, integer
- **user_id** — ID of the user that owns the gallery, integer
- **name** — Title of the gallery, string
- **description** — Description of the gallery, string
- **cover_photo** - Array containing a JSON hash of the cover photo's id, size, url, and nsfw flag
- **subtitle** — A short (500 char.) blurb of the gallery, string
- **items_count** — Number of items in the gallery, integer
- **privacy** - Boolean value whether or not the gallery is private. A value of true means the gallery is private to the user
- **kind** - Indicates the **[gallery kind][]**, integer
- **created\_at** — Timestamp indicating time the gallery was created, timestamp
- **updated\_at** — Timestamp indicating time the gallery was updated, timestamp
- **custom_path** - A slug for the gallery url, string
- **editors_choice** - Boolean value indicating whether the gallery has been featured in editor's choice
- **feature** - Name of stream where gallery has been featured. Values can be either 'popular' or 'fresh'
- **featured_at** - Timestamp indicating when gallery was featured
- **token** - Token signature for a private gallery url. Only returned if request is made by the gallery owner
- **user** _(optional)_ - User who owns the gallery, in **[short format][]**
***
## Equipment object formats
### Camera info
- **id** - ID of the camera, integer
- **friendly_name** - Displayable name, eg. "Canon EOS 70D"
- **name** - Actual name of the camera, eg. "EOS 70D"
- **verified** - Whether or not this entry is verified, true or false
- **features** - Short list of features, HTML-formatted string
- **slug** - The slug, eg "eos-70d",
- **camera_type** - The type of camera this is, one of
- dslr
- film
- smartphone
- mirrorless
- compact
- medium_format
- film_scanner
- action_camera
- drone
- **brand** - A small object containing brand info, eg.
```
{
"id": 1,
"name": "Canon",
"slug": "canon"
}
```
### Lens info
- **id** - ID of the lens, integer
- **friendly_name** - Displayable name, eg. "Canon EF-S 10-18mm f/4.5-5.6 IS STM"
- **name** - Actual name of the lens, eg. "EF-S 10-18mm f/4.5-5.6 IS STM"
- **slug** - The slug, eg. "ef-s-10-18mm-f-4-5-5-6-is-stm"
- **features** - Short list of features, HTML-formatted string
- **brand** - A small object containing brand info, eg.
```
{
"id": 1,
"name": "Canon",
"slug": "canon"
}
```
[Category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[gallery kind]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#gallery-kinds
[License type]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#license_types
================================================
FILE: basics/terms_of_use.md
================================================
# Terms of Use
This agreement sets out the terms and conditions (the "API Terms of Use") pursuant to which you are licensed by 500px Inc. ("500px") to use the 500px application programming interfaces (the "500px APIs"). By accessing or using 500px APIs in any way you acknowledge and agree on your own behalf and on behalf of the company or entity you represent ("You") that you have read, understand and agree to be bound by the API Terms of Use, our 500px site terms [http://500px.com/terms](http://500px.com/terms) and our 500px site privacy policy [http://500px.com/privacy](http://500px.com/privacy), (collectively the "500px Agreement") all of which shall govern your relationship with 500px and your access to its members. 500px reserves the right to alter, delete and/or add to the 500px Agreement at its discretion. You can always find the most recent version of 500px Agreement on the following pages: [https://github.com/500px/api-documentation/blob/master/basics/terms_of_use.md](https://github.com/500px/api-documentation/blob/master/basics/terms_of_use.md).
If you disagree with any part of the API Terms of Use or any other terms of the 500px Agreement, 500px does not grant you a license to use the 500px APIs and you are directed to immediately cease using the 500px APIs.
## Purpose
The purpose of the 500px APIs is to permit registered users ("API Users") to develop applications that interface with the 500px site for the purpose of importing, exporting and sharing content and data with the 500px website and providing products and services to its members.
## Registration
To become an API User you must register and be approved by 500px. As part of the registration and approval process you will be asked to provide your name, email and contact information, the name, email and contact information of the entity or company you represent, as well as details about the 500px API application you intend to develop and/or the products and/or services you intend to offer to 500px members using the 500px API. It is your responsibility to ensure the information provided to 500px is complete, true and accurate throughout your period as a 500px API User. If you provide any information that is untrue, inaccurate, not current or incomplete, or 500px has reasonable grounds to suspect that such information is untrue, inaccurate, not current or incomplete, 500px may terminate your 500px API license and/or the 500px Agreement.
During registration, you may be asked to provide an e-mail address and to create your own password. Your e-mail address will become your user identification. Upon being accepted as an API User you will be issued one or more API keys for use with your 500px APIs. You are responsible for maintaining the confidentiality of the password and your API keys and are fully responsible for all activities that occur under your password and API keys. You agree to immediately notify 500px of any unauthorized use of your password, API keys or any other breach of security. 500px reserves the right to approve and authorize API Users at its discretion.
## Grant of 500px API License
The 500px APIs are owned by 500px Inc. Upon your acceptance as an API User you are hereby granted a non-exclusive, non-sublicensable, worldwide license to use each 500px API and API Key delivered to you by 500px for the purpose authorized in your registration and acceptance as an API User, subject to the terms and conditions contained in these API Terms of Use and the other parts of your 500px Agreement. The terms and conditions of your 500px Agreement apply to all copies of the 500px APIs made by or for you, and to all updates, revisions, and substitutions, if any.
Photos and images on the 500px site are owned by 500px members and not by 500px. All rights not expressly granted to you are reserved by 500px and/or its members.
## 500px API License Conditions and Restrictions
### You shall at all times:
- **Provide attribution credit to the copyright owner (Photographer member of 500px) as well as a hyperlink to 500px website photo page adjacent to each use. Format for credit should read as "© Photographer Name / 500px"**
- Comply with the API Terms of Use and the other terms and conditions of your 500px Agreement, [http://500px.com/terms](http://500px.com/terms) and [http://500px.com/privacy](http://500px.com/privacy).
- Comply with any terms, conditions and copyright restrictions imposed on usage of photos and images by their respective member owners. 500px doesn't own the images; 500px members do. Although the 500px APIs can be used to gain access to photos, images and other information of 500px members, neither 500px’s provision of the 500px APIs to you nor your use of the 500px APIs override the owner member’s terms, conditions and copyright restrictions which may include "all rights reserved" and "private" restrictions, Creative Commons licenses and/or other terms and conditions that must be agreed upon between you and the member. You are solely responsible for making use of 500px photos, images and member other information in compliance with the member’s requirements and/or restrictions.
- Remove from your application within 24 hours any 500px member’s photos, images or other information that the owner asks you to remove.
- Disclose in your application through a privacy policy or statement otherwise displayed in the footer of each page, how you collect, use, store, and disclose data collected from visitors, including, where applicable, that third parties (including advertisers) may serve content and/or advertisements and collect information directly from visitors and may place or recognize cookies on visitors' browsers.
- Provide 500px reasonable access to usage analytics of the application.
### You shall not:
- Use 500px APIs for any application or purpose other than as approved by 500px.
- Use 500px APIs for any application that replicates or attempts to replace the essential user experience of the 500px.com website or software applications built by 500px.
- Attempt to cloak or conceal your identity or your application’s identity when requesting authorization to use 500px APIs.
- Display more than 20 500px photos or images per page in your application or use an unreasonable amount of bandwidth.
- Cache or store any photos or images obtained from 500px for more than 24 hours.
- Enable downloads or storage of photos that are protected by copyright by any application.
- Use 500px as a generic image hosting service for banner advertisements, graphics, etc.
- Use 500px APIs in a manner that adversely impacts the stability of 500px.com servers or adversely impacts the behavior of other applications using the 500px APIs.
- Sell, lease, or sublicense 500px APIs or access thereto or derive revenues from the use or provision of 500px APIs, whether for direct commercial or monetary gain or otherwise, except as set forth below.
#### Without limiting the generality of the foregoing, Use 500px APIs, post, email, transmit, upload or otherwise submit any content to 500px members that:
- is offensive to the 500px online community, such as content that promotes racism, bigotry, hatred or physical harm of any kind against any group or individual;
could be harmful to minors;
- harasses or advocates harassment of another person;
- involves the transmission of "junk mail", "chain letters", or unsolicited mass mailing or "spamming";
- promotes information that is false, misleading, illegal or promotes illegal activities or conduct that is abusive, threatening, obscene, defamatory or libelous;
- infringes any patent, trademark, trade secret, copyright or other proprietary rights of any person including, without limitation, promoting an illegal or unauthorized copy of another person's copyrighted work, such as providing pirated computer programs or links to them, providing information to circumvent manufacture-installed copy-protect devices, or providing pirated music or links to pirated music files;
- violates any law or regulation, any right of any person, including but not limited to intellectual property rights, rights of privacy, or rights of personality;
- contains restricted or password only access pages, or hidden pages or images (those not linked to or from another accessible page);
- displays pornography or pornographic material of any kind;
- provides material that exploits people under the age of 18 in a sexual or violent manner, or solicits personal information from anyone under the age of 18;
- provides instructional information about illegal activities such as making or buying illegal weapons, violating someone's privacy, or providing or creating computer viruses;
- solicits 500px passwords or personal identifying information for unlawful purposes from 500px members;
- engages in contests, sweepstakes, barter, advertising, and pyramid schemes, without our prior written consent;
- promotes or is used in connection with spyware, adware, other malicious programs or code; and
- contains or will contain any disabling mechanism or protection feature designed to prevent its use, including any clock, timer, counter, computer virus, worm, software lock, drop dead device, Trojan horse routine, trap door, time bomb or any other codes, designs, routines or instructions that may be used to access, modify, replicate, distort, delete damage or disable any content, any services or any 500px application, or web site or any operating system software or hardware on which such content, service application or website is operated or displayed.
## Termination
A separate license to use a 500px API is granted each time the related API Key is made available to you. You may terminate a 500px API license by providing notice to 500px and discontinuing use of the related 500px API.
500px may terminate a 500px API license or the 500px Agreement, at any time for any reason. Your rights to use the 500px APIs terminate automatically if (i) you violate any terms of your 500px Agreement, (ii) 500px publicly posts a written notice of termination on 500px.com, (iii) 500px sends a written notice of termination to you, or (iv) 500px disables the API Key and access to the 500px APIs.
## Trademark License
"500px", the 500px logo and such other trademarks and logos that are from time to time used by 500px are proprietary trademarks of 500px Inc (the "500px Trademarks"). API Users are hereby granted a non-exclusive, non-sublicensable, worldwide license to use 500px Trademarks as follows. All other uses are strictly prohibited.
You shall place the following statement prominently on your 500px API application: "This product uses the 500px API but is not endorsed or certified by 500px."
You may use 500px Trademarks with the prior written consent of 500px. Any approved use of 500px Trademarks will require that the 500px Trademark be less prominent than the logo or mark that primarily describes the application and be accompanied by the following statement: "This [application/website] uses the 500px(tm) API and is not endorsed or certified by 500px or 500px Inc. All 500px Trademarks displayed on this [application/website] are property of 500px Inc."
You shall not use "500px" in your product name, domain name, or images.
You shall not use a 500px Trademark in any manner that implies endorsement of your company, its products and/or services or the 500px API application by 500px.
## Ownership
The 500px APIs are the sole and exclusive property of 500px and its licensors and all copyright, patent, trademarks and other intellectual property rights therein are owned or licensed by and are proprietary to 500px and its licensors. 500px’s rights apply to the 500px APIs and all output and executables of the 500px APIs, excluding any software components developed by you which do not themselves incorporate the 500px APIs or any output or executables of the 500px APIs. You agree to abide by all applicable proprietary rights laws and other laws, as well as any additional copyright notices or restrictions contained in these terms.
## Support
500px may elect to provide you with support or modifications for the 500px APIs (collectively, "Support"), in its sole discretion, and may terminate such Support at any time without notice to you. 500px may change, suspend, or discontinue any aspect of the 500px APIs at any time, including the availability of any 500px APIs. 500px may also impose limits on certain features and services or restrict your access to parts or all of the 500px APIs or the 500px web site without notice or liability.
## Fees and Payments
500px is committed to free and open access to our APIs. However, providing the APIs does have real costs for 500px. For uses of 500px APIs over a reasonable rate or for certain types of commercial applications, 500px reserves the right to charge fees for future use of or access to the 500px APIs or to terminate your 500px API license.
## Disclaimer of Warranty
SOME OF THE 500PX API(S) MAY BE EXPERIMENTAL AND NOT TESTED IN ANY MANNER. 500PX DOES NOT REPRESENT OR WARRANT THAT ANY 500PX API(S) ARE FREE OF INACCURACIES, ERRORS, BUGS, OR INTERRUPTIONS, OR ARE RELIABLE, ACCURATE, COMPLETE, OR OTHERWISE VALID.
THE 500PX API(S) ARE PROVIDED "AS IS" WITH NO WARRANTY, EXPRESS OR IMPLIED, OF ANY KIND AND 500PX EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES AND CONDITIONS, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, SECURITY, TITLE AND/OR NON-INFRINGEMENT. 500PX MAKES NO REPRESENTATION OR WARRANTY REGARDING, IS NOT RESPONSIBLE FOR, AND DISCLAIMS ALL LIABILITY FOR, THE CONTINUED AVAILABILITY, RELIABILITY, ACCURACY, RESULTS OR PERFORMANCE OF 500PX.COM OR ANY MATERIAL ON 500PX.COM, THE PERFORMANCE OF THE INTERNET, THE DOWNLOADING COMPATIBILITY OF ANY MATERIALS OR SOFTWARE WITH YOUR COMPUTER SYSTEM, THE EXISTENCE OF ANY VIRUS, WORM, MALICIOUS CODE OR OTHER DISABLING DEVICE FROM ANY SOURCE, THE UNAUTHORIZED ACCESS TO OR USE OF YOUR INFORMATION BY A PERSON, CORPORATION OR ENTITY OTHER THAN 500PX, ANY TECHNICAL FAILURES (INCLUDING HARDWARE OR SOFTWARE FAILURES), INCOMPLETE, SCRAMBLED, OR DELAYED COMPUTER TRANSMISSIONS, AND/OR TECHNICAL INACCURACIES, OR LOSS OR USE OF DATA, AS WELL AS UNAUTHORIZED ACCESS OF USER TRANSMISSIONS BY THIRD PARTIES.
YOUR USE OF 500PX API(S) IS AT YOUR OWN DISCRETION AND RISK, AND YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE THAT RESULTS FROM THE USE OF ANY 500PX API(S) INCLUDING, BUT NOT LIMITED TO, ANY DAMAGE TO YOUR COMPUTER SYSTEM OR LOSS OF DATA.
## Limitation of Liability
500PX ITS DIRECTORS, OFFICERS, SHAREHOLDERS, EMPLOYEES, CONSULTANTS, AND AGENTS SHALL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO YOU FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR EXEMPLARY DAMAGES ARISING OUT OF OR IN CONNECTION WITH USE OF THE 500PX API(S), WHETHER BASED ON BREACH OF CONTRACT, BREACH OF WARRANTY, TORT (INCLUDING NEGLIGENCE, PRODUCT LIABILITY OR OTHERWISE), OR ANY OTHER PECUNIARY LOSS, WHETHER OR NOT NOTICE HAS BEEN PROVIDED TO ANY SUCH PERSON OR ENTITY OF THE POSSIBILITY OF SUCH DAMAGES. UNDER NO CIRCUMSTANCES SHALL 500PX ITS DIRECTORS, OFFICERS, SHAREHOLDERS, EMPLOYEES, CONSULTANTS AND AGENTS BE LIABLE TO YOU FOR ANY AMOUNT IN EXCESS OF $100.
YOU EXPRESSLY ACKNOWLEDGE THAT 500PX HAS ENTERED INTO AND GRANTED YOU THE LICENSES CONTAINED IN THE API TERMS OF USE IN RELIANCE UPON THE LIMITATIONS AND EXCLUSIONS OF LIABILITY AND THE DISCLAIMERS SET FORTH HEREIN, AND THAT THEY FORM AN ESSENTIAL BASIS OF THE BARGAIN BETWEEN YOU AND 500PX. YOU EXPRESSLY AGREE THE LIMITATIONS AND EXCLUSIONS OF LIABILITY AND THE DISCLAIMERS SET FORTH IN THE API TERMS OF USE SHALL SURVIVE, AND CONTINUE TO APPLY IN THE CASE OF, FUNDAMENTAL BREACH OR BREACHES, THE FAILURE OF ESSENTIAL PURPOSE OF CONTRACT, THE FAILURE OF ANY EXCLUSIVE REMEDY OR TERMINATION OF YOUR ACCESS TO AND USE OF 500PX.COM AND ITS CONTENT.
SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES. ACCORDINGLY, SOME OF THE ABOVE LIMITATIONS OF SECTIONS 10 AND 11 MAY NOT APPLY TO YOU.
## Release and Waiver of Liability
To the maximum extent permitted by applicable law, you hereby release and waive all claims against 500px its subsidiaries, affiliates and their respective directors, officers, employees, consultants, agents co-branders and other partners from any and all liability for claims, damages (actual and/or consequential), costs and expenses (including litigation costs and attorneys’ fees) of every kind and nature, arising from or in any way related to your use of 500px APIs. You expressly waive and relinquish any and all rights and benefits which you may have under any provincial, state or federal statute or common law principle of similar effect, to the fullest extent permitted by law.
## Indemnification
To the maximum extent permitted by applicable law, you agree to defend, indemnify and hold harmless 500px its subsidiaries, affiliates and their respective directors, officers, employees, consultants, agents co-branders or other partners from and against any third party claim arising from or in any way related to your use of 500px APIs, including any liability or expense arising from all claims, losses, damages (actual and/or consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. 500px shall use good faith efforts to provide you with written notice of such claim, suit or action.
## Arbitration
Any controversy, claim or dispute arising out of or relating to the 500px Agreement including without limitation, the performance, breach, enforcement, existence or validity of the 500px Agreement which cannot be resolved by 500px and you (a "Claim"), shall be referred to and finally settled (to the exclusion of the courts) by private and confidential binding arbitration before a single arbitrator in Toronto, Ontario, Canada in English pursuant to the Arbitration Act 1991, (Ontario), as amended, replaced or re-enacted from time to time. The arbitrator shall be a person who is trained in law and who has experience in the information technology field in Canada and is independent of you and 500px. Any such Claim shall be arbitrated on an individual basis, and shall not be consolidated in any arbitration with any claim, controversy or dispute of any other person, corporation or entity. You agree to waive any right you may have to commence or participate in any class action against 500px related to any Claim and you agree to opt out of any class proceedings against 500px. However, 500px reserves the right to refer any Claim in respect of intellectual property to the Federal Court of Canada.
## General Terms
Notwithstanding any provision hereof, for all purposes of the 500px Agreement, you and 500px shall be and act independently and not as partner, joint venturer, agent, employee or employer of the other. You shall not have any authority to assume or create any obligation for or on behalf of 500px, express or implied, and you shall not attempt to bind 500px to any contract.
The 500px Agreement constitutes the entire agreement between 500px and you about your use of 500px APIs and, except as specifically set forth in the 500px Agreement, supersede any prior agreements between you and 500px relating to the 500px APIs your access to and use of 500px.com and its content. 500px may assign the 500px Agreement, in whole or in part, at any time. 500px’s failure to insist upon or enforce strict performance of any right or provision of the 500px Agreement shall not constitute or be construed as a waiver of any right or provision. If any of the provisions (or parts thereof) contained in the 500px Agreement, as amended from time to time, are determined to be void, invalid or otherwise unenforceable by a court of competent jurisdiction, such determination shall not affect the remaining provisions (or parts thereof) contained in the 500px Agreement which shall remain in full force and effect and shall be construed as if the invalid provision had been omitted. The section headings and subheadings contained in the 500px Agreement are included for convenience only, and shall not limit or otherwise affect the terms of the 500px Agreement. Any construction or interpretation to be made of the 500px Agreement shall not be construed against the drafter. 500px and you have required that the Terms of Use and all documents relating thereto be drawn up in English. Les parties ont demandé que cette convention ainsi que tous les documents que s’y rattachent soient rédigés en anglais (Version française). In the event of a conflict between the English and French version of these terms, the English version shall prevail.
Published on August 16, 2011. Modified on May 29, 2012.
================================================
FILE: basics/upload.md
================================================
# Uploading a photo
To upload a photo, you need to do 2 requests:
1. `POST /photos`
1. `POST url-obtained-from-first-request`
First, send a `POST` request to `/photos` ([see documentation](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md)) with the photo details like title, description and so on. You may also want to set the `privacy` parameter to `1` if you wish to do a private upload or `0` for public upload. Finally, you can pass `auto_activate` parameter set to `true` to have to photo marked active as soon as it is uploaded.
This request will return a JSON with the upload `url` and a data structure that you need to use for the second request. Here's an example of [such data structure taken from the `POST /photos`](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md#example)
``` json
"presigned_post": {
"url": "https://s3.amazonaws.com/photos.500px.net",
"fields": {
...
}
}
```
The second request is uploading the file itself. You do that by sending a POST request to the `url` that you obtained from the previous request. The body of the request must be in the multipart form-data format and must have all the properties from the `fields` structure that was returned in the first request. NOTE: the order matters, you need to supply the `fields` in the exact same order you received it. The last parameter is the file to be uploaded in the `file` field.
Here's an example request, the fields are `form-data`:
```
POST https://s3.amazonaws.com/photos.500px.net
name="key" 238921583/cb47e80843a0eaaaaac2fc242c9cd6bcecd6f36/0.jpg
name="x-amz-meta-user_id" 16972409
name="x-amz-meta-client_application_id" 0
name="x-amz-meta-user_agent" Chrome/62.0.3202.94 Safari/537.36
name="x-amz-meta-user_ip" 206.223.171.146
name="policy" eyJleHBpcmF0aW9uIjoiMjAxN...
name="x-amz-credential" ASDASDASDASDASD/20171212/us-east-1/s3/aws1_request
name="x-amz-algorithm" AWS4-HMAC-SHA256
name="x-amz-date" 20171212T195326Z
name="x-amz-signature" 47aa1...
name="file"; filename="IMG_20171028_175620-01.jpeg"
Content-Type: image/jpeg
...the file contents...
```
***
## Return format
`POST /photos` will return HTTP status 200 on success. Proceed with the second request only when you get back the 200 status.
`POST url-from-first-request` will return HTTP status 204 upon successful upload.
================================================
FILE: endpoints/collections/DELETE_collections_id.md
================================================
### DEPRECATED
Please use the corresponding **[galleries endpoint][]**
***
# Collections Resources
DELETE collections/:collection_id
## Description
Deletes collection.
***
## Requires authentication
**[OAuth][]**
***
## Return format
**TODO**
***
## Errors
None
***
## Example
**Request**
GET v1/collections
**Return**
**TODO**
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/DELETE_galleries_id.md
================================================
FILE: endpoints/collections/GET_collections.md
================================================
### DEPRECATED
Please use the corresponding **[galleries endpoint][]**
***
# Collections Resources
GET collections
## Description
Returns a listing of all User's collections and sets.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **photos_per_collection_limit** — The number of photos included in each collection. Can not be over 200, default 200.
***
## Return format
A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
***
## Errors
None
***
## Example
**Request**
GET v1/collections
**Return**
``` json
{
"collections": [
{
"id": 289621,
"title": "Film set",
"position": 0,
"created_at": "2012-05-24T10:13:34-04:00",
"path": "film_set",
"photos": [
{
"id": 7905188,
"name": "St Lawrence Market Toronto",
"rating": 0,
"created_at": "2012-05-24T11:22:46-04:00",
"category": 3,
"image_url": "http://pcdn.500px.net/7905188/9e1fcf034f7492c92d0f98e504d80c0b80e15990/4.jpg",
"votes_count": 0,
"position": 1
},
{
"id": 7905189,
"name": "Distillery district Toronto",
"rating": 0,
"created_at": "2012-05-24T11:22:49-04:00",
"category": 3,
"image_url": "http://pcdn.500px.net/7905189/cc0ff39d30614fea56f2583ec796460d6a05d69c/4.jpg",
"votes_count": 0,
"position": 2
}
]
},
{
"id": 298603,
"title": "Bikes set",
"position": 1,
"created_at": "2012-06-07T13:15:26-04:00",
"path": "bikes_set",
"photos": [
{
"id": 7651996,
"name": "bike",
"rating": 48.7,
"created_at": "2012-05-16T11:47:12-04:00",
"category": 26,
"image_url": "http://pcdn.500px.net/7651996/bfc9a0ae7cfaed28ebc947c2d4cd79e60a04934d/4.jpg",
"votes_count": 2,
"position": 1
}
]
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries.md
================================================
FILE: endpoints/collections/GET_collections_id.md
================================================
### DEPRECATED
Please use the corresponding **[galleries endpoint][]**
***
# Collections Resources
GET collections/:id
## Description
Returns a collection.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **image_size** - Numerical size of the image to link to, 1 being the smallest and 4 being the largest. Multiple image sizes may be specified as ```image_size[]=2&image_size[]=4```.
***
## Return format
A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
***
## Errors
None
***
## Example
**Request**
GET v1/collections/52&image_size=3
**Return**
``` json
{
"id": 52,
"title": "models",
"position": 0,
"created_at": "2012-06-04T13:55:08-04:00",
"path": "models",
"kind": "portfolio",
"photos": [
{
"id": 500,
"name": "Maria | portrait 1",
"rating": 0,
"created_at": "2012-06-04T10:18:18-04:00",
"category": 0,
"image_url": "http://dpcdn.500px.net/500/1e38495dab54fbe8bcc3b7a3679ee8f52e34cc8f/4.jpg",
"images":[
{"size":3,
"url":"http://dpcdn.500px.org/500/9661dc2247a00f115456a3af08b804cb61d493cd/3.jpg?v=0",
"https_url":"https://gp1.wac.edgecastcdn.net/806614/photos/photos.500px.net/500/9661dc2247a00f115456a3af08b804cb61d493cd/3.jpg?v=0"}],
"votes_count": 0,
"position": 999
},
{
"id": 499,
"name": "Maria | portrait 2",
"rating": 0,
"created_at": "2012-06-04T10:18:12-04:00",
"category": 0,
"image_url": "http://dpcdn.500px.net/499/3a323000e7b9ca7676b01de3916543c479e636f0/4.jpg",
"images":[
{"size":3,
"url":"http://ppcdn.500px.org/499/573b00d542f811de627c4cbb0fb1c1c09b76e729/3.jpg?v=0",
"https_url":"https://gp1.wac.edgecastcdn.net/806614/photos/photos.500px.net/499/573b00d542f811de627c4cbb0fb1c1c09b76e729/3.jpg?v=0"}]
"votes_count": 0,
"position": 999
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md
================================================
FILE: endpoints/collections/POST_collections.md
================================================
### DEPRECATED
Please use the corresponding **[galleries endpoint][]**
***
# Collections Resources
POST collections
## Description
Creates new a collection.
***
## Requires authentication
**[OAuth][]**
## Parameters
Essential information:
- **title** _(required)_ — Title for the collection.
- **path** _(required)_ — Path where the collection will be accessible at 500px.com/user/sets/:path.
- **kind** — Kind of the Collection to be created Recognized values: 1 - Portfolio Set (default), 2 - Profile Set.
- **photo_ids** — Comma separated list of Photo ID values to post with the blog.
Optional information:
- **position** — Position of the collection in the list of collections.
***
## Return format
A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
***
## Errors
- **path** — path of the collection has already been taken.
- **403 Forbidden** — You have to upgrade to create portfolios and sets.
***
## Example
**Request**
POST v1/collections?title=bikes&path=bikes
**Return**
``` json
{
"id": 298782,
"title": "bikes",
"position": 10,
"created_at": "2012-06-07T17:36:17-04:00",
"path": "bikes",
"photos": []
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/POST_galleries.md
================================================
FILE: endpoints/collections/PUT_collections_id.md
================================================
### DEPRECATED
Please use the corresponding **[galleries endpoint][]**
***
# Collections Resources
PUT collections/:id
## Description
Updates collection.
***
## Requires authentication
**[OAuth][]**
## Parameters
Essential information:
- **id** _(required)_ — Collection ID.
- **title** — Title for the collection.
- **path** — Path where the collection will be accessible at 500px.com/user/sets/:path.
- **photo_ids** — Comma separated list of Photo ID values that are in this collection.
- **kind** — Change kind of the Collection. Recognized values: 1 - Portfolio Set, 2 - Profile Set.
Optional information:
- **position** — Position of the collection in the list of collections.
***
## Return format
A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
***
## Errors
None
***
## Example
**Request**
PUT v1/collections/298603?title=Bikes&photo_ids=7651996
**Return**
``` json
{
id: 298603,
title: "Bikes",
position: 0,
created_at: "2012-06-07T13:15:26-04:00",
path: "bikes_set",
photos: [
{
id: 7651996,
name: "bike",
rating: 48.7,
created_at: "2012-05-16T11:47:12-04:00",
category: 26,
image_url: "http://pcdn.500px.net/7651996/bfc9a0ae7cfaed28ebc947c2d4cd79e60a04934d/4.jpg",
votes_count: 2,
position: 999
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id.md
================================================
FILE: endpoints/comments/POST_comments_id_comments.md
================================================
# Comment Resources
POST comments/:id/comments
## Description
Creates a reply to an existing comment. Comments can only be nested one level deep, you cannot reply to a reply of a comment. If a comment has a non-null parent_id value then it cannot be replied to.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **body** _(required)_ — Content of the comment.
***
## Return format
A JSON object with key "status" and value of 200, a key "message" with value of "Successfully added a comment.", and a key of "comment" including the comment model of the comment that was created.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The body of the comment was not specified.
- **404 Not Found** — The specified comment was not found.
***
## Example
**Request**
POST v1/comments/73249443/comments
**Body**
body=Nice+color+and+composition.
**Result**
``` json
{
"status" : 200,
"message" : "Successfully added a comment.",
"error" : "None"
"comment": {
"id": 83858343,
"user_id": 198867,
"to_whom_user_id": 347823,
"body": "Nice color and composition.",
"created_at": "2013-02-25T17:35:26-05:00",
"parent_id": 73249443,
"flagged": false,
"rating": 0,
"voted": false,
"user": {
"id": 198867,
"username": "tye",
"firstname": "Tye",
"lastname": "Shavik",
"city": "Toronto",
"country": "Canada",
"fullname": "Tye Shavik",
"userpic_url": "http://acdn.500px.net/198867/7f5f29fd33e093062a30e2bf3a9e605c446ba960/1.jpg?29",
"upgrade_status": 2,
"followers_count": 36,
"affection": 103,
"admin": 1
}
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/galleries/DELETE_galleries_id.md
================================================
# Galleries Resources
DELETE users/:user_id/galleries/:id
## Description
Deletes the gallery.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The ID of the gallery to delete.
***
## Return format
A JSON object containing keys: **status**, **message** and **error** (if an error occurred).
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — You do not own the gallery you are trying to delete.
- **404 Not Found** — The gallery you are trying to delete does not exist, or is private (and you are not its owner)
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/galleries/GET_galleries.md
================================================
# Galleries Resources
GET users/:user_id/galleries
## Description
Returns a listing of twenty (up to one hundred) galleries for the given user.
***
## Requires authentication
* A valid Consumer Key must be provided in the **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **sort** — Sort galleries in the specified order.
###### Recognized values:
- 'created_at' — Sort by time of creation
- 'updated_at' — Sort by time of last change (photo added or removed). This is the default.
- 'last_added_to_at' — Sort by time last photo was added to the gallery.
- 'rating' — Sort by gallery rating
- 'position' — Sort by gallery position (as defined by the user)
- **cover_size** — The cover photo size to be returned, if `include_cover` is set. Defaults to 4.
- **include_cover** — If 1, the user's cover is included.
- **sort_direction** — Control the order of the sorting. You can provide a **sort_direction** without providing a **sort**, in which case the default sort is used.
###### Recognized values:
- 'asc' — Sort in ascending order (lowest or least-recent first). This is the default.
- 'desc' — Sort in descending order (highest or most-recent first).
- **privacy** — The privacy level of the galleries to return.
###### Recognized values:
- 'private' — Only include the user's private galleries in the response. Only available for the current user.
- 'public' — Only include the user's public galleries in the response. This is the default.
- 'both' - Include both the public and private galleries in the response. Only available for the current user.
- **kinds** — A comma-separated list of **[gallery kinds][]**. Default is to return all galleries.
- **page** — Return a specific page in the photo stream. Page numbering is 1-based.
- **rpp** — The number of results to return. Cannot be over 100, default 20.
***
## Return format
A JSON object with the following keys and values:
- **filters** — Additional filters that were used:
- 'privacy' — The value of the privacy filter used;
- 'kinds' — The value of the **[gallery kinds][]** requested;
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **galleries** — An array of Gallery objects in **[short format][]**.
***
## Errors
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-3
[gallery kinds]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#gallery-kinds
================================================
FILE: endpoints/galleries/GET_galleries_id.md
================================================
# Galleries Resources
GET users/:user_id/galleries/:id
## Description
Returns the details of the requested gallery
`:id` can be one of the following:
* gallery id
* gallery path
* gallery token
Gallery id and path can be used to access any publicly-shared galleries, while
knowing a gallery's secret token allows access to the corresponding private galler (regardless of ownership).
The gallery id can be used to access any gallery owned by the current user (public or private).
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **cover_size** — The cover photo size to be returned. Defaults to 4.
***
## Return format
The requested Gallery object in **[full format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **404 Not Found** — The gallery you are requesting does not exist, or is private (and you are not its owner)
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format-3
================================================
FILE: endpoints/galleries/GET_galleries_id_items.md
================================================
# Galleries Resources
GET users/:user_id/galleries/:id/items
## Description
Returns a listing of twenty (up to one hundred) photos in the given gallery.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **only** — String name of the **[category][]** to return photos from. **Note:** Case sensitive, separate multiple values with a comma.
- **exclude** — String name of the **[category][]** to exclude photos by. **Note:** Case sensitive, separate multiple values with a comma.
- **sort** — Sort photos in the specified order.
###### Recognized values:
- 'created_at' — Sort by time of upload.
- 'rating' — Sort by rating.
- 'highest_rating' — Sort by the highest rating the photo reached.
- 'times_viewed' — Sort by view count.
- 'votes_count' — Sort by number of likes.
- 'comments_count' — Sort by number of comments.
- 'taken_at' — Sort by the original date of the image extracted from metadata (might not be available for all images).
- 'position' — Sort by the user's manually defined order. This is the default.
- **sort_direction** — Control the order of the sorting. You can provide a **sort_direction** without providing a **sort**, in which case default sort will be used.
###### Recognized values:
- 'asc' — Sort in ascending order (lowest or least-recent first). This is the default.
- 'desc' — Sort in descending order (highest or most-recent first).
- **page** — Return a specific page in the photo stream. Page numbering is 1-based.
- **rpp** — The number of results to return. Cannot be over 100, default 20.
- **image_size** — The photo size to be returned. It has to be an integer: 1 to 4. Also an array is accepted:
###### Example:
- '&image_size=3'
- '&image_size[]=3&image_size[]=4'
- **include_store** — If set to 1, returns market infomation about the photo.
###### Returned values:
- 'store_download' — Boolean value if the picture is avaliable for HD Download purchase.
- 'store_print' — Boolean value if the picture is avaliable for Canvas print purchase.
- 'store_license' — Boolean value if the picture is avaliable for Prime purchase.
- 'store_width' — Integer value indicating the store size of the photo.
- 'store_height' — Integer value indicating the store size of the photo.
- **include_states** — If set to 1, returns state of the photo for the currently logged in user and authenticated request.
###### Returned values:
- 'liked' — Boolean value whether the current user has liked this photo
- 'purchased' — Boolean value whether the current user has bought this photo
- **include_tags** (or **tags**) — If set to 1, returns an array of tags for the photo.
- **include_missing** — If set to 1, returns ids of photos that have been deleted, made private or the owner of the photo is deactivated.
- **include_geo** — If set to 1, returns location information about the photo.
- **include_licensing** — If set to 1, returns licensing information for the photo.
***
## Return format
A JSON object with the following keys and values:
- **filters** — Additional filters that were used:
- 'category' — The ID of the **[category][]** that photos were filtered by;
- 'exclude' - The ID of the **[category][]** that photos were excluded;
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **photos** — An array of Photo objects in **[short format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **404 Not Found** — The gallery you are requesting does not exist, or is private (and you are not its owner)
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format
================================================
FILE: endpoints/galleries/GET_galleries_id_share_url.md
================================================
# Galleries Resources
```
GET users/:user_id/galleries/:id/share_url
```
# Description
Returns a sharable private URL for the given gallery.
# Requires authentication
* Requires a valid **[OAuth][]** request with an authorized Access Token.
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
# Parameters
None
# Return format
```json
{
"share_url" : "g/<some token>"
}
```
# Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **404 Not Found** — The gallery you are requesting does not exist, or is private (and you are not its owner)
================================================
FILE: endpoints/galleries/POST_galleries.md
================================================
# Galleries Resources
POST users/:user_id/galleries
## Description
Creates a new, empty gallery owned by the given user.
***
## Requires authentication
**[OAuth][]**
## Parameters
- **name** _(required)_ — Name for the gallery.
- **description** — Description of the gallery. Default is blank.
- **subtitle** — Subtitle of the gallery. Default is blank.
- **privacy** — If 1, the gallery is marked private, otherwise it is public. Default is public.
- **kind** _(required)_ - Must be one of the following **[gallery kinds][]**.
- **custom_path** - A slug that the gallery will be accessible through. Needs to be unique to the user.
***
## Return format
A JSON object containing **status** and **gallery** with the new Gallery object in **[full format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **403 Forbidden** — You are not the user who will own the new gallery.
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format-3
[gallery kinds]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#gallery-kinds
================================================
FILE: endpoints/galleries/PUT_galleries_id.md
================================================
# Galleries Resources
PUT users/:user_id/galleries/:id
## Description
Updates the metadata for the given gallery.
***
## Requires authentication
**[OAuth][]**
## Parameters
- **name** — Sets the title for the gallery.
- **description** — Description of the gallery.
- **subtitle** — Updates the subtitle of the gallery.
- **privacy** — If 1, the gallery is marked private, otherwise it is public.
- **cover_photo_id** — Updates the gallery's cover photo, must be
a pre-existing item in the gallery with valid photo and user.
- **custom_path** - A slug that the gallery will be accessible through. Needs to be unique to the user.
If a field is not provided, its current value is retained.
***
## Return format
A JSON object with the key **gallery** that contains the updated Gallery object in **[full format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **404 Not Found** — Photo with the specified ID does not exist.
- **403 Forbidden** — You are not the owner of the gallery.
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format-3
================================================
FILE: endpoints/galleries/PUT_galleries_id_items.md
================================================
# Galleries Resources
PUT users/:user_id/galleries/:id/items
## Description
Adds, removes, or updates the order of items in the gallery.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
The input to this method should be a JSON body with these fields:
- **add** — An optional hash directing that photos be inserted (or moved), in the following format:
- **after** - If present, the items will be inserted after the described item. The **after** option is a hash in the following format:
- **id** - The ID of the photo to insert the items after. If **id** is **null**, the photos are inserted at the beginning of the gallery.
- **before** - If present, the items will be inserted before the described item. The **before** option is a hash in the following format:
- **id** - The ID of the photo to insert the items before. If **id** is **null**, the photos are inserted at the end of the gallery.
- **photos** - An array of Photo IDs to insert.
- **remove** — Am optional hash directing that photos be removed, in the following format:
- **photos** - An array of Photo IDs to remove.
You cannot specify both **before** and **after** in a single request. If the ID of the photo in a **before** or **after** does not exist in the gallery, an error is returned. If neither **before** nor **after** are provided, the photos are inserted at the beginning of the gallery.
You can provided an **add** or a **remove** directive, or both. If both directives are provided, the remove directive is performed first, so if a photo's ID appears in both directives, it will end up being present in the gallery after the operation completes.
You can provide photos in the **add** directive that are already present in the gallery. The result of doing this will be to reorder the gallery so that the photos are removed from their current position (as if they had been included in the **remove** directive) and then added at the new position.
It is an error to provide a photo as both a **before** or **after** and as a photo to insert.
***
## Return format
An object mapping photo IDs to the operation performed ("added" or "removed"), see example.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **403 Forbidden** — The gallery is not owned by you.
- **403 Forbidden** — The photo was either deleted, is private, or belongs to a deactivated user.
- **404 Not Found** — The gallery you are requesting does not exist.
- **404 Not Found** — A photo you tried to add does not exist.
## Example
**Request**
PUT v1/users/23/galleries/4/items
``` json
{
"add": {
"after": { "id": 5 },
"photos": [ 1, 2, 3 ]
},
"remove": {
"photos": [ 1, 4, 5 ]
}
}
```
**Return**
``` json
{
"1": { "result": "added" },
"2": { "result": "added" },
"3": { "error": "Not found", "status": 404 },
"4": { "result": "removed" },
"5": { "result": "removed" }
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
================================================
FILE: endpoints/galleries/PUT_galleries_reposition.md
================================================
# Galleries Resources
PUT users/:user_id/galleries/reposition
## Description
Bulk repositions galleries. Accepts a set of gallery ids, and repositions them in the given order at the end of the list of galleries. Optionally, galleries can be positioned relative to an existing gallery by specifying a `before_id` or `after_id`. **Specifying both will return an error**.
***
## Requires Authentication
**[OAuth][]**
## Parameters
- **galleries** _(required)_ - The set of gallery ids to reposition, separated by commas
- **before_id** - The id of another gallery to position the galleries before
- **after_id** - The id of another gallery to position the galleries after
***
## Return format
Returns a JSON hash of gallery ids, and their reposition completion status (success or error)
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **401 Unauthorized** - You are not authenticated through OAuth.
- **403 Forbidden** — You are not the owner of one or more of the galleries.
- **404 Not Found** — One or more of the galleries with a specified ID does not exist.
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-3
================================================
FILE: endpoints/photo/DELETE_photos_id.md
================================================
# Photo Resources
DELETE photos/:id
## Description
Deletes the photo from the User's library.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The Photo ID to delete.
***
## Return format
A JSON object containing keys: **status**, **message** and **error**(if happened).
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — You do not own the photo you are trying to delete.
- **404 Not Found** — The requested photo does not exist or was deleted.
***
## Example
**Request**
DELETE v1/photos/8359543
**Return**
``` json
{
"status": 200,
"message": "Successfully deleted a photo.",
"error": "None"
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/photo/DELETE_photos_id_tags.md
================================================
# Photo Resources
DELETE photos/:id/tags
## Description
Removes tags from the photo. Accepts one or multiple coma separated tags.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The Photo ID to remove tags from.
- **tags** _(required)_ — Coma separated tags.
***
## Return format
A JSON object with key "status" and value of 200, and key "message" with value of "Successfully deleted tags."
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **404 Not Found** — The photo was not found.
***
## Example
**Request**
DELETE /v1/photos/8309863/tags?tags=cute,puppy
**Return**
``` json
{
"status":200,
"message":"Successfully deleted tags.",
"error":"None"
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/photo/DELETE_photos_id_vote.md
================================================
# Photo Resources
DELETE photos/:photo_id/vote
## Description
Unlikes the specified photo for the user.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The Photo ID to unlike.
***
## Return format
A JSON object containing keys: **status**, **message**, **photo** (in **[short format][]**) and **error**(if happened).
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **404 Not Found** — The requested photo does not exist or was deleted.
***
## Example
**Request**
DELETE v1/photos/8359543/vote
**Return**
``` json
{
"status": 200,
"message": "Successfully unliked photo.",
"photo": {
"id": 12345,
"name": "photo1",
...
}
"error": "None"
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format
================================================
FILE: endpoints/photo/GET_photos.md
================================================
# Photo Resources
GET photos
## Description
Returns a listing of twenty (up to one hundred) photos for a specified **[photo stream][]**.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **feature** _(required)_ — Photo stream to be retrieved. Default *fresh_today*. Recognized values:
###### Global features
- 'popular' — Return photos in Popular. Default sort: rating.
- 'highest_rated' — Return photos that have been in Popular. Default sort: highest_rating.
- 'upcoming' — Return photos in Upcoming. Default sort: time when Upcoming was reached.
- 'editors' — Return photos in Editors' Choice. Default sort: time when selected by an editor.
- 'fresh_today' — Return photos in Fresh Today. Default sort: time when reached fresh.
- 'fresh_yesterday' — Return photos in Fresh Yesterday. Default sort: same as 'fresh_today'.
- 'fresh_week' — Return photos in Fresh This Week. Default sort: same as 'fresh_today'.
###### Per-user features
All per-user streams require a **user_id** or **username** parameter
- 'user' - Return photos of a user, additional parameter 'user_id' or 'username' is required. Default sort: time uploaded.
- 'user_friends' — Return photos by users the specified user is following. Default sort: time uploaded.
- **only** — String name of the **[category][]** to return photos from. **Note:** Case sensitive, separate multiple values with a comma.
- **exclude** — String name of the **[category][]** to exclude photos by. **Note:** Case sensitive, separate multiple values with a comma.
- **sort** — Sort photos in the specified order.
###### Recognized values:
- 'created_at' — Sort by time of upload
- 'rating' — Sort by rating
- 'highest_rating' — Sort by the highest rating the photo reached
- 'times_viewed' — Sort by view count
- 'votes_count' — Sort by votes count
- 'comments_count' — Sort by comments count
- 'taken_at' — Sort by the original date of the image extracted from metadata (might not be available for all images)
- **sort_direction** — Control the order of the sorting. You can provide a **sort_direction** without providing a **sort**, in which case the default sort for the requested feature will be adjusted.
###### Recognized values:
- 'asc' — Sort in ascending order (lowest or least-recent first)
- 'desc' — Sort in descending order (highest or most-recent first). This is the default.
- **page** — Return a specific page in the photo stream. Page numbering is 1-based.
- **rpp** — The number of results to return. Can not be over 100, default 20.
- **image_size** — The photo size(s) to be returned. See the documentation on **[photo sizes][]**.
- **include_store** — If set to 1, returns market infomation about the photo.
###### Returned values:
- 'store_download' — Boolean value if the picture is avaliable for HD Download purchase.
- 'store_print' — Boolean value if the picture is avaliable for Canvas print purchase.
- **include_states** — If set to 1, returns state of the photo for the currently logged in user and authenticated request.
###### Returned values:
- 'liked' — Boolean value whether the current user has liked this photo
- 'purchased' — Boolean value whether the current user has bought this photo
- **personalized_categories** - If set to true, returns photos from personalized categories for the currently logged in user and authenticated request, if personalization is available for the current user.
- **tags** — If set to 1, returns an array of tags for the photo.
- **followers_count** - Filter the photo stream by number of followers each photo's user has. The expected value is `operator:N`. `Operator` can be one of `eq ne lt lte gt gte` (details below) and `N` is the number of followers. At the time of this documentation, the default for "Undiscovered photographers" is `lt:200`.
- eq = `equals`
- ne = `not equals`
- lt = `less than`
- lte = `less than or equals`
- gt = `greater than`
- gte = `greater than or equals`
***
## Return format
An array with the following keys and values:
- **feature** — Feature that is being returned.
- **filters** — Additional filters that were used:
- 'category' — The ID of the **[category][]** that photos were filtered by;
- 'user_id' — The ID of the user specified by 'user_id' or 'username' parameters;
- 'friends_ids' — IDs of users the user specified is following;
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **photos** — An array of Photo objects in **[short format](https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format)**.
***
## Errors
None
***
## Example
**Request**
https://api.500px.com/v1/photos?feature=popular
**Return** __shortened for example purpose__
``` json
{
"feature": "popular",
"filters": {
"category": false,
"exclude": false
},
"current_page": 1,
"total_pages": 250,
"total_items": 5000,
"photos": [
{
"id": 4910421,
"name": "Orange or lemon",
"description": "",
"times_viewed": 709,
"rating": 97.4,
"created_at": "2012-02-09T02:27:16-05:00",
"category": 0,
"privacy": false,
"width": 472,
"height": 709,
"votes_count": 88,
"comments_count": 58,
"nsfw": false,
"image_url": "http://pcdn.500px.net/4910421/c4a10b46e857e33ed2df35749858a7e45690dae7/2.jpg",
"user": {
"id": 386047,
"username": "Lluisdeharo",
"firstname": "Lluis ",
"lastname": "de Haro Sanchez",
"city": "Sabadell",
"country": "Catalunya",
"fullname": "Lluis de Haro Sanchez",
"userpic_url": "http://acdn.500px.net/386047/f76ed05530afec6d1d0bd985b98a91ce0ce49049/1.jpg?0",
"upgrade_status": 0
}
},
{
"id": 4905955,
"name": "R E S I G N E D",
"description": "From the past of Tagus River, we have History and memories, some of them abandoned and disclaimed in their margins ...",
"times_viewed": 842,
"rating": 97.4,
"created_at": "2012-02-08T19:00:13-05:00",
"category": 0,
"privacy": false,
"width": 750,
"height": 500,
"votes_count": 69,
"comments_count": 29,
"nsfw": false,
"image_url": "http://pcdn.500px.net/4905955/7e1a6be3d8319b3b7357c6390289b20c16a26111/2.jpg",
"user": {
"id": 350662,
"username": "cresendephotography",
"firstname": "Carlos",
"lastname": "Resende",
"city": "Forte da Casa",
"country": "Portugal",
"fullname": "Carlos Resende",
"userpic_url": "http://acdn.500px.net/350662.jpg",
"upgrade_status": 0
}
}
]
}
```
[photo stream]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[http://500px.com/:username]: http://500px.com/iansobolev
[http://500px.com/:username/following]: http://500px.com/iansobolev/following
[category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[photo sizes]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#image-urls-and-image-sizes
================================================
FILE: endpoints/photo/GET_photos_id.md
================================================
# Photo Resources
GET photos/:id
## Description
Returns detailed information of a single photo.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **image_size** — Numerical size of the image to link to, 1 being the smallest and 4 being the largest.
- **comments** — Return comments to the photo in the response. Comments are returned in order of creation, 20 entries per page. If omitted no comments will be returned, if present comments will be returned.
- **comments_page** — Return the specified page from the comments listing. Page numbers are 1-based.
- **tags** — Returns an array of tags for the photo. If omitted no tags will be returned, if present tags will be returned.
***
## Return format
A JSON object containing keys **photo** and **comments**, where **photo** is a Photo object in **[full format][]** and comments is a list of **comments** associated with the photo in the following format:
- **id** — ID of the comment.
- **user_id** — The ID of the author of the comment.
- **to_whom_user_id** — Is always the ID of the author of the photo.
- **body** — Text of the comment.
- **created_at** - Creation of the comment
- **parent_id** - Parent comment in case this comment is a reply.
- **user** — Profile of the author of the comment in **[short format][]**.
### When requested with OAuth authentication, following keys will be included in the photo object:
- **voted** — Whether the current user has voted for this photo, boolean
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The photo was either deleted, belongs to a deactivated user.
- **404 Not Found** — Photo with the specified ID does not exist.
***
## Example
**Request**
v1/photos/4928401?comments
**Return** __shortened for example purpose__
``` json
{
"photo": {
"id": 4928401,
"user_id": 164677,
"name": "Northern Fulmar",
"description": "Photographed during a pelagic trip east of Cape Cod. This seabird species only comes to land to nest and stays on the open sea the rest of the year. They can drink saltwater and excrete the excess salt through a gland on top of the bill.",
"camera": "Canon EOS-1D Mark IV",
"lens": "",
"focal_length": "700",
"iso": "400",
"shutter_speed": "1/2000",
"aperture": "6.3",
"times_viewed": 167,
"rating": 97.1,
"status": 1,
"created_at": "2012-02-09T21:11:53-05:00",
"category": 11,
"location": null,
"privacy": false,
"latitude": 41.75968637583948,
"longitude": -68.935546875,
"taken_at": "2010-11-13T08:37:37-05:00",
"hi_res_uploaded": 0,
"for_sale": false,
"width": 588,
"height": 750,
"votes_count": 36,
"comments_count": 36,
"nsfw": false,
"sales_count": 0,
"for_sale_date": null,
"highest_rating": 97.1,
"highest_rating_date": "2012-04-16T15:05:56-04:00",
"image_url": "http://pcdn.500px.net/4928401/16666558d7ba410f50922f86f736888d8cfaf9bb/4.jpg",
"images": {"size": 4, "url": "http://pcdn.500px.net/4928401/16666558d7ba410f50922f86f736888d8cfaf9bb/4.jpg"}
"store_download": false,
"store_print": false,
"voted": false,
"purchased": false,
"user": {
"id": 164677,
"username": "axelhildebrandt",
"firstname": "Axel",
"lastname": "Hildebrandt",
"city": "Bethlehem",
"country": "U.S.",
"fullname": "Axel Hildebrandt",
"userpic_url": "http://acdn.500px.net/164677.jpg",
"upgrade_status": 0
}
},
"comments": [
{
"id": 8482806,
"user_id": 584607,
"to_whom_user_id": 164677,
"body": "Test",
"created_at": "2012-04-16T15:07:54-04:00",
"parent_id": null,
"user": {
"id": 584607,
"username": "ArseniyIvanov",
"firstname": "Arseniy",
"lastname": "Ivanov",
"fullname": "Arseniy Ivanov",
"userpic_url": "http://acdn.500px.net/584607/36708ac62be191405639ad071f6bb772186c8679/1.jpg?103",
"upgrade_status": 2
}
},
{
"id": 8477321,
"user_id": 413718,
"to_whom_user_id": 164677,
"body": "Like!",
"created_at": "2012-02-10T00:59:44-05:00",
"parent_id": null,
"user": {
"id": 413718,
"username": "SilviaSil",
"firstname": "Silvia",
"lastname": "S.",
"fullname": "Silvia S.",
"userpic_url": "/graphics/userpic.png",
"upgrade_status": 0
}
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/photo/GET_photos_id_comments.md
================================================
# Comment Resources
GET photos/:id/comments
## Description
Returns a listing of twenty comments for the photo.
***
## Requires authentication
A valid Consumer Key must be provided in **consumer_key** parameter.
***
## Parameters
- **id** _(required)_ — The Photo ID to get comments for.
- **page** — Return a specific page in the comment listing. Page numbering is 1-based.
- **nested** - Include this parameter to return the comments in nested format.
***
## Return format
An array with the following keys and values:
- **media_type** — The type of object the comment belongs to (for blog comments this will be "blog_post").
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **comments** — An array of Comment objects in **full format** or **nested format** if you specified the `nested` parameter.
***
## Errors
- **404 Not Found** — The requested photo does not exist or was deleted.
***
## Example
**Request**
v1/photos/4928401/comments
**Return** (shortened for example purposes)
``` json
{
"media_type": "photo",
"current_page": 1,
"total_pages": 2,
"total_items": 36,
"comments": [
{
"id": 8471866,
"user_id": 122216,
"to_whom_user_id": 164677,
"body": "Great image of a fascinating bird. Love the topside view.",
"created_at": "2012-02-09T21:13:32-05:00",
"parent_id": null,
"user": {
"id": 122216,
"username": "haig",
"firstname": "John",
"lastname": "Haig",
"city": "1000 Islands Twp.",
"country": "Canada",
"fullname": "John Haig",
"userpic_url": "http://acdn.500px.net/122216/bd556f88c7fb9eaee93ff74c057a313c8911071a/1.jpg?48",
"upgrade_status": 2
}
},
{
"id": 8471883,
"user_id": 81920,
"to_whom_user_id": 164677,
"body": "The details on the feathers are perfect. Brilliant shot. ",
"created_at": "2012-02-09T21:14:04-05:00",
"parent_id": 8471866,
"user": {
"id": 81920,
"username": "wisben",
"firstname": "Manny ",
"lastname": "Estrella",
"city": "Arlington",
"country": "USA",
"fullname": "Manny Estrella",
"userpic_url": "http://acdn.500px.net/81920.jpg",
"upgrade_status": 0
}
}
]
}
```
**Nested Format**
```json
{
"media_type": "photo",
"current_page": 1,
"total_pages": 2,
"total_items": 36,
"comments": [
{
"id": 8471866,
"user_id": 122216,
"to_whom_user_id": 164677,
"body": "Great image of a fascinating bird. Love the topside view.",
"created_at": "2012-02-09T21:13:32-05:00",
"parent_id": null,
"user": {
"id": 122216,
"username": "haig",
"firstname": "John",
"lastname": "Haig",
"city": "1000 Islands Twp.",
"country": "Canada",
"fullname": "John Haig",
"userpic_url": "http://acdn.500px.net/122216/bd556f88c7fb9eaee93ff74c057a313c8911071a/1.jpg?48",
"upgrade_status": 2
},
"replies": [
{
"id": 8471883,
"user_id": 81920,
"to_whom_user_id": 164677,
"body": "The details on the feathers are perfect. Brilliant shot. ",
"created_at": "2012-02-09T21:14:04-05:00",
"parent_id": 8471866,
"user": {
"id": 81920,
"username": "wisben",
"firstname": "Manny ",
"lastname": "Estrella",
"city": "Arlington",
"country": "USA",
"fullname": "Manny Estrella",
"userpic_url": "http://acdn.500px.net/81920.jpg",
"upgrade_status": 0
}
}
]
}
]
}
````
================================================
FILE: endpoints/photo/GET_photos_id_votes.md
================================================
# Photo Resources
GET photos/:id/votes
## Description
Returns all users that had liked this photo.
***
## Requires authentication
* A valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **page** — Return a specific page in the photo stream. Page numbering is 1-based.
- **rpp** — The number of results to return. Can not be over 100, default 20.
***
## Return format
A JSON object containing users that liked that photo.
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **users** — Profile of the author of the comment in **[short format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The photo was either deleted, belongs to a deactivated user.
- **404 Not Found** — Photo with the specified ID does not exist.
***
## Example
**Request**
v1/photos/4928401/votes
**Return** __shortened for example purpose__
``` json
{
"current_page": 1,
"total_pages": 27,
"total_items": 534,
"users": [
{
"id": 477772,
"username": "danendid",
"firstname": "Estetic of",
"lastname": "Senses",
"city": "Brussels",
"country": "Belgium",
"fullname": "Estetic of Senses",
"userpic_url": "http://acdn.500px.net/477772/fca7121758c49b13d33511662f0ecb4abb4097e9/1.jpg?126",
"upgrade_status": 0
},
{
"id": 490956,
"username": "LK_fine_artist",
"firstname": "Christian",
"lastname": "Lamos",
"city": "Budapest",
"country": "Hungary",
"fullname": "Christian Lamos",
"userpic_url": "http://acdn.500px.net/490956/a5e57c142d21242c0d37de1e4f3b5f3688447a22/1.jpg?10",
"upgrade_status": 0
},
{
"id": 843534,
"username": "Agnieszkauczywo",
"firstname": "Agnieszka",
"lastname": "Łuczywo",
"city": null,
"country": null,
"fullname": "Agnieszka Łuczywo",
"userpic_url": "/graphics/userpic.png",
"upgrade_status": 0
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/photo/GET_photos_search.md
================================================
# Photo Resources
GET photos/search
## Description
Returns a listing of twenty (up to one hundred) photos from search results for a specified tag, keyword, or location.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
Either of parameters **term**, **tag**, or **geo** is required.
- **term** — A keyword to search for.
- **tag** — A complete tag string to search for.
- **geo** — A geo-location point of the format `latitude,longitude,radius<units>`. Acceptable `units` are `km` or `mi`.
- **only** — String name of the **[category][]** to return photos from. **Note:** Multiple categories may be given, separated by commas, e.g. `Fashion,Black and White`
- **was_featured_type** - search only certain feature categories, the [accepted values are the same as for the `GET /photos` endpoint](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos.md#global-features)
- **exclude** — String name of the **[category][]** to exclude from the results. **Note:** Multiple categories may be given, separated by commas, e.g. `People,Nude`
- **exclude_nude=1** - Specifically exclude all photos marked as NSFW. **Note:** We do our best to ensure all NSFW photos are marked as such, but we are unable to guarantee that this will always be the case.
- **page** — Return a specific page. Page numbering is 1-based.
- **rpp** — The number of results to return. Can not be over 100, default 20.
- **tags** — Returns an array of tags for each photo.
- **user_id** — Limit your search within photos of the given user.
- **image_size** — The photo size(s) to be returned. See the documentation on **[photo sizes][]**.
- **license_type** -- Restrict the results to one or more **[license types][]**. Multiple types can be separated with a comma: `license_type=1,4`.
- **sort** — Sort photos in the specified order. The following values are recognized:
- **_score** — Sort by query score, best match first.
- **created_at** — Default: sort by time of upload, most recent first.
- **rating** — Sort by current rating, highest rated first.
- **highest_rating** — Sort by highest rating achieved, highest rated first.
- **times_viewed** — Sort by the number of views, most viewed first.
- **votes_count** – Sort by the number of votes, most voted on first.
- **comments_count** — Sort by the number of comments, most commented first.
- **taken_at** — Sort by the original date of the image extracted from metadata, most recent first (might not be available for all images).
## Return format
An array with the following keys and values:
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **photos** — An array of Photo objects in **[short format][]**. The objects will also include `latitude` and `longitude` attributes if the results are based on the geo-location search.
***
## Errors
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
***
## Example
**Request**
GET v1/photos/search?term=bike
## Return __shortened for example purpose__
``` json
{
"current_page": 1,
"total_pages": 50,
"total_items": 8263,
"photos": [
{
"id": 4930535,
"name": "Bike",
"description": "",
"times_viewed": 28,
"rating": 27,
"created_at": "2012-02-10T00:39:03-05:00",
"category": 21,
"privacy": false,
"width": 2500,
"height": 1883,
"votes_count": 1,
"comments_count": 0,
"nsfw": false,
"image_url": "http://pcdn.500px.net/4930535/140c1f84fb63be76884b2b60350c6b6d75c2433f/2.jpg",
"user": {
"id": 171927,
"username": "MarkBrunner",
"firstname": "mark",
"lastname": "Brunner",
"city": "Haslett",
"country": "united States",
"fullname": "mark Brunner",
"userpic_url": "http://acdn.500px.net/171927.jpg",
"upgrade_status": 0
}
},
{
"id": 4930206,
"name": "Rain",
"description": "",
"times_viewed": 1,
"rating": 59.7,
"created_at": "2012-02-10T00:04:09-05:00",
"category": 21,
"privacy": false,
"width": 4542,
"height": 3042,
"votes_count": 1,
"comments_count": 1,
"nsfw": false,
"image_url": "http://pcdn.500px.net/4930206/bedeed09e5a15014c558aa59de29bd40c4212811/2.jpg",
"user": {
"id": 578359,
"username": "mikecruzphotography",
"firstname": "Mike",
"lastname": "Cruz",
"city": "",
"country": "Singapore",
"fullname": "Mike Cruz",
"userpic_url": "http://acdn.500px.net/578359/600796b98145b21fb3b35bc7c5ce001db1b4ea4a/1.jpg?127",
"upgrade_status": 0
}
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[license types]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#license-types
[photo sizes]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#image-urls-and-image-sizes
================================================
FILE: endpoints/photo/POST_photos.md
================================================
# Photo Resources
POST photos
## Description
Create a new photo on behalf of the user, and receive an **[upload key][]** in exchange.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
Essential information:
- **name** — Title of the photo
- **description** — Description for the photo
- **category** — A numerical ID for the **[Category][]** of the photo
- **auto_activate** - Set this to 'true' if the photo should be automatically marked as active as soon as it's uploaded. It this parmeter is not included, the photo will not be automatically marked as active after upload.
Technical details of the photo: (this information may be overridden when the file is uploaded and parsed for EXIF and IPTC tags)
- **shutter_speed** — Shutter speed in seconds, represented by string containing a rational expression if the value is <1 sec., or a decimal value if the value is >1sec.
- **focal_length** — Focal length in millimetres, a string representing an integer value
- **aperture** — Aperture value
- **iso** — ISO value
- **camera** — Make and model of the camera. Note: Please make sure it contains sensible information (eg., does not contain camera's make or model twice)
- **lens** — Lens used to make this photo
### Geographical information of the photo:
- **latitude** — Latitude, in decimal format
- **longitude** — Longitude, in decimal format
### Optional attributes:
- **tags** — Comma-separated list of tags to apply to the photo.
- **privacy** — Whether to hide the photo from the user profile on the website. Otherwise, the photo is only available for use in Collections/Portfolio. Recognized values: 1 for private, 0 for public.
***
## Return format
Status code 200, along with a JSON array containing photo and 'upload_key' keys, where value of photo is an object representing the Photo information in **[short format][]**, and **['upload_key'](https://github.com/500px/api-documentation/blob/master/authentication/upload_key.md)** is the token to be used by the client to upload the file. Also included is **['presigned_post'](https://github.com/500px/api-documentation/blob/master/authentication/presigned_post.md)** this is to be used for authenticating a direct upload to S3.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **422 Unprocessable Entity** — The system had trouble saving the record. You may retry again.
***
## Example
**Request**
POST v1/photos?name=Hello&description=World&tags=some,useful,tags
**Return**
``` json
{
"upload_key": "89653832030e7d26daf3a43fc2ccd501",
"presigned_post": {
"url": "https://s3.amazonaws.com/photos.500px.net",
"fields": {
"key": "...",
"x-amz-meta-user_id": "173",
"x-amz-signature": "...",
"x-amz-algorithm": "...",
"x-amz-credential": "...",
"x-amz-date": "20120608131704Z"
},
},
"photo": {
"id": 10000277,
"user_id": 173,
"name": "Hello",
"description": "World",
"camera": null,
"lens": null,
"focal_length": null,
"iso": null,
"shutter_speed": null,
"aperture": null,
"times_viewed": 0,
"rating": null,
"status": 0,
"created_at": "2012-06-08T13:17:14-04:00",
"category": 0,
"location": null,
"privacy": false,
"latitude": null,
"longitude": null,
"taken_at": null,
"hi_res_uploaded": 0,
"for_sale": false,
"width": null,
"height": null,
"votes_count": 0,
"comments_count": 0,
"nsfw": false,
"sales_count": 0,
"for_sale_date": null,
"highest_rating": 0,
"highest_rating_date": null
}
}
```
[upload key]: https://github.com/500px/api-documentation/blob/master/authentication/upload_key.md
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[Category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
================================================
FILE: endpoints/photo/POST_photos_id_comments.md
================================================
# Photo Resources
POST photos/:id/comments
## Description
Creates a new comment for the photo.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The Photo ID to post comments for.
- **body** _(required)_ — Content of the comment.
***
## Return format
A JSON object with key "status" and value of 200, a key "message" with value of "Successfully added a comment.", and a key of "comment" including the comment model of the comment that was created.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The body of the comment was not specified.
- **404 Not Found** — The photo was not found.
***
## Example
**Request**
POST /v1/photos/8309863/comments
**Body**
body=I+like+your+photo
**Return**
``` json
{
"status":200,
"message":"Successfully added a comment.",
"error":"None",
"comment": {
"id": 83858343,
"user_id": 198867,
"to_whom_user_id": 347823,
"body": "I like your photo",
"created_at": "2013-02-25T17:35:26-05:00",
"parent_id": null,
"flagged": false,
"rating": 0,
"voted": false,
"user": {
"id": 198867,
"username": "tye",
"firstname": "Tye",
"lastname": "Shavik",
"city": "Toronto",
"country": "Canada",
"fullname": "Tye Shavik",
"userpic_url": "http://acdn.500px.net/198867/7f5f29fd33e093062a30e2bf3a9e605c446ba960/1.jpg?29",
"upgrade_status": 2,
"followers_count": 36,
"affection": 103,
"admin": 1
}
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/photo/POST_photos_id_report.md
================================================
# Photo Resources
POST photos/:id/report
## Description
Allows to report a photo.
***
## Parameters
- **id** _(required)_ — ID of the photo to report.
- **reason** _(required)_ — Reason for the report
- '1' — Offensive (rude, obscene)
- '2' — Spam (ads, self-promotion)
- '3' — Offtopic (trolling)
- '4' — Copyright (plagiarism, stealing)
- '5' — Wrong content (illustration, 3D)
- '6' — Should be tagged as adult content
- '0' — Other, request should ideally also include **reason_details**
- **reason_details** — Additional information about the report, as a text blob
***
## Return format
A JSON object containing success attribute.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **404 Not Found** — Photo with the specified ID does not exist.
***
## Example
**Request**
POST /v1/photos/112116/report
**Return**
``` json
{
"success": true
}
```
================================================
FILE: endpoints/photo/POST_photos_id_tags.md
================================================
# Photo Resources
POST photos/:id/tags
## Description
Adds tags to the photo. Accepts one or multiple coma separated tags.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — The Photo ID to add tags for.
- **tags** _(required)_ — Coma separated tags.
***
## Return format
A JSON object with key "status" and value of 200, and key "message" with value of "Successfully added tags."
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **404 Not Found** — The photo was not found.
***
## Example
**Request**
POST /v1/photos/8309863/tags
**Body**
tags=cute,puppy
**Return**
``` json
{
"status":200,
"message":"Successfully added tags.",
"error":"None"
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
================================================
FILE: endpoints/photo/POST_photos_id_vote.md
================================================
# Photo Resources
POST photos/:id/vote
## Description
Allows the user to vote for a photo.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
- **id** _(required)_ — ID of the photo the vote is cast upon.
- **vote** _(required)_ — vote, values: '0' for 'dislike' or '1' for 'like'.
***
## Return format
A JSON object containing key **photo**, where **photo** is a Photo object in [full format][].
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
- **403 Forbidden** — The vote has been rejected; common reasons are: current user is inactive, has not completed their profile, is trying to vote on their own photo, or has already voted for the photo.
- **404 Not Found** — Photo with the specified ID does not exist.
***
## Example
**Request**
POST /v1/photos/112116/vote?vote=1
**Return**
``` json
{
"photo": {
"id": 4928402,
"user_id": 69241,
"name": "Guitar",
"description": "",
"camera": "Canon EOS rebel T2i",
"lens": null,
"focal_length": "35",
"iso": "400",
"shutter_speed": "1/20",
"aperture": "2",
"times_viewed": 4,
"rating": 27,
"status": 1,
"created_at": "2012-02-09T21:12:01-05:00",
"category": 5,
"location": null,
"privacy": false,
"latitude": null,
"longitude": null,
"taken_at": "2012-02-09T14:50:29-05:00",
"hi_res_uploaded": 0,
"for_sale": false,
"width": 5184,
"height": 3456,
"votes_count": 1,
"comments_count": 0,
"nsfw": false,
"sales_count": 0,
"for_sale_date": null,
"highest_rating": 66.5287,
"highest_rating_date": "2009-11-14T09:26:56-05:00",
"image_url": "http://pcdn.500px.net/4928402/5868f8b7f020e4f7ce75fd8f1b66c6f75f53bd4f/4.jpg",
"user": {
"id": 69241,
"username": "rileywiebe",
"firstname": "Riley",
"lastname": "Wiebe",
"city": "Swift Current",
"country": "Canada",
"fullname": "Riley Wiebe",
"userpic_url": "http://acdn.500px.net/69241.jpg",
"upgrade_status": 0
}
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/photo/PUT_photos_id.md
================================================
# Updating a Photo's Information
PUT photos/:id
## Description
Allows the client application to update user-editable information on a photo.
## Resource URL
https://api.500px.com/v1/photos/:id
## Authentication
**Required;** [OAuth][]. The client application must use the OAuth access token issued for the owner of the photo to access this resouce.
## Parameters
The application must provide the ID of the photo to update in the URL of the request. The following parameters are recognized when included in the query string or POST body:
- **name**: Title of the photo, up to 255 characters in length.
- **description**: Text description of the photo, up to 65535 characters in length.
- **category**: Integer number of the category of the photo. See [category mapping][] for exact values.
- **tags**: Comma-separated list of tags applicable to this photo.
- **add_tags**: Comma-separated list of tags to add to this photo's existing tags.
- **remove_tags**: Comma-separated list of tags to remove from this photo's existing tags.
- **shutter_speed**: Shutter speed value for the photo, internally stored as string.
- **focal_length**: Focal length value for the photo, internally stored as string.
- **aperture**: Aperture value value for the photo, internally stored as string.
- **iso**: Integer ISO value for the photo.
- **camera**: Make and model of the camera used to take this photo.
- **lens**: Information about the lens used to take this photo.
- **latitude**: Latitude of the location this photo was taken at represented by a decimal number.
- **longitude**: Longitude of the location this photo was taken at represented by a decimal number.
- **nsfw**: Boolean value indicating that the photo may contain not-safe-for-work content or content not suitable for minors.
- **license_type**: Integer number of the license type chosen for this photo. See [license type mapping][] for exact values.
- **privacy**: Integer value indicating that the photo should be shown (`0`) or hidden (`1`) on the user's profile.
- **crop**: A hash containing keys `x`, `x2`, `y`, `y2` and representing coordinates within which the thumbnail must be cropped. The crop is made using the top left corner as the origin. The points must be given relative to image size `4`, an image of at most 900px on the larger side. The client application may skip this if the user does not wish to change photo thumbnail.
## Implementation details
A parameter missing from the request will not be updated. A parameter set to an empty string or null value will be interpreted as the user wishing to reset the value of the field to its default value.
You can use the `add_tags` and `remove_tags` parameters to manupulate a photo's tags without having to send the complete list of tags in the request.
## Return format
A JSON object containing key **photo**, where **photo** is a Photo object in **[full format][]**.
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **401: Invalid OAuth request**: The request was refused because the OAuth signature is incorrect.
- **404: Photo with ID not found**: The photo ID provided is not known to the system.
- **404: Photo with ID has been deleted**: The photo has been deleted and can not be edited.
- **404: Photo with ID belongs to a deactivated user**: The photo belongs to a user that is no longer active and can not be edited.
- **400: Bad photo category**: An unrecognized photo category value has been provided.
- **400: Bad license type**: An unrecognized license type value has been provided.
***
## Example
**Request**
PUT v1/photos/40840326?name=Toronto%20Sky%20vs%20City%20Hall&category=9&description=A%20panoramic%20shot%20taken%20with%20an%20Android%20camera%20on%20the%20evening%20of%20Jul%2019th.
**Return**
```
{
"photo": {
"id": 40840326,
"user_id": 3798,
"name": "Toronto Sky vs City Hall",
"description": "A panoramic shot taken with an Android camera on the evening of Jul 19th.",
"camera": "Nexus 4",
"lens": null,
"focal_length": null,
"iso": "",
"shutter_speed": null,
"aperture": null,
"times_viewed": 2,
"rating": 0.0,
"status": 1,
"created_at": "2013-07-20T01:14:52-04:00",
"category": 9,
"location": null,
"privacy": 0,
"latitude": null,
"longitude": null,
"taken_at": "2013-07-19T20:59:26-04:00",
"hi_res_uploaded": 0,
"for_sale": false,
"width": 3464,
"height": 1608,
"votes_count": 0,
"comments_count": 0,
"sales_count": 0,
"highest_rating": 0.0,
"highest_rating_date": null,
"license_type": 0,
"converted": 27,
"image_url": "http://pcdn.500px.net/40840326/c828635b422c28af135f255f9a8323c16ea8340a/4.jpg",
"user": {
"id": 3798,
"username": "freeatnet",
"firstname": "Arseniy",
"lastname": "Ivanov",
"city": "Toronto",
"country": "Canada",
"fullname": "Arseniy Ivanov",
"userpic_url": "http://acdn.500px.net/3798/25f3e0e4783a25983b79df3a3966461f3ca10d57/1.jpg?1",
"upgrade_status": 2,
"followers_count": 156,
"affection": 90,
"admin": 1
}
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[category mapping]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
[license type mapping]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#license-types
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/template.md
================================================
# Photo Resources
GET example/:id
## Description
***
## Requires authentication
***
## Parameters
***
## Return format
***
## Errors
***
## Example
**Request**
Code Example
**Return**
Code Example
[photo stream]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
[category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
================================================
FILE: endpoints/user/DELETE_users_id_friends.md
================================================
# User Resources
DELETE users/:id/friends
## Description
Removes the user from the list of followers.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **id** _(required)_ — ID of the User to remove from the followers list.
***
## Return format
A JSON array with un-followed User object.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The user requested has been disabled or not in followers list.
- **404 Not Found** — User does not exist in our database.
***
## Example
**Request**
DELETE v1/users/827595/friends
**Return**
``` json
{
user: {
id: 827595,
username: "voldemarpetruskauskus",
firstname: "Voldemar",
lastname: "Petruskauskus",
birthday: null,
sex: 0,
city: "",
state: "",
country: "",
registration_date: "2012-05-15T11:19:42-04:00",
about: "Voldemar",
domain: null,
upgrade_status: 9,
fotomoto_on: false,
locale: "en",
show_nude: false,
store_on: false,
contacts: { },
equipment: { }
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
================================================
FILE: endpoints/user/GET_users.md
================================================
# User Resources
GET users
## Description
Returns the profile information for the current user.
***
## Requires authentication
**[OAuth][]**
***
## Parameters
None
***
## Return format
Current user's profile information in **[full format][]**.
Additional data:
- **upload_limit** — the number of photos the user may upload at this moment, integer.
- **upload_limit_expiry** — date and time of the beginning of the new upload limit cycle, datetime.
- **show_personalized_categories** - checks if the user can see personalized photo categories, boolean.
- **gdpr_acceptance_timestamp** - timestamp of when a user accepted the GDPR-compliant EULA.
***
## Errors
None.
***
## Example
**Request (Using [OAuth][])**
https://api.500px.com/v1/users
**Return**
``` json
{
"user": {
"id": 173,
"username": "vovko",
"firstname": "Voldemar",
"lastname": "Petruskauskus",
"birthday": null,
"sex": 0,
"city": "",
"state": "",
"country": "",
"active": 1,
"registration_date": "2009-11-08T12:41:14-05:00",
"about": "lbalblabla",
"domain": "vovko.500px.com",
"upgrade_status": 2,
"fotomoto_on": false,
"locale": "en",
"show_nude": true,
"store_on": false,
"contacts": {
"website": "www.drizhepolov.com",
"twitter": "vovko",
"livejournal": "vovko",
"flickr": "Vladimir Drizhepolov",
"gtalk": "vladimir@drizhepolov.com",
"skype": "trulllllll",
"facebook": "562874260",
"facebookpage": "www.facebook.com/vovko"
},
"equipment": {
"camera": [
"Kiev 88",
"Lomo Rocket",
"Lomo Action sampler"
],
"lens": [
"Volna 80mm"
]
},
"fullname": "Voldemar Petruskauskus",
"userpic_url": "http://acdn.500px.net/173.jpg",
"email": "vladimir@drizhepolov.com",
"photos_count": 5,
"galleries_count": 5,
"affection": 7,
"friends_count": 37,
"followers_count": 7,
"upload_limit": null,
"upload_limit_expiry": "2012-06-08T14:30:28-04:00",
"upgrade_status_expiry": "2012-12-12",
"show_personalized_categories": true,
"auth": {
"facebook": 0,
"twitter": 0
}
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#profile-format
================================================
FILE: endpoints/user/GET_users_id_followers.md
================================================
# User Resources
GET users/:id/followers
## Description
Returns a list of users who follow the specified user.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **id** _(required)_ — ID of the user.
- **page** — Return the specified page of the resource. Page numbering is 1-based.
- **rpp** — Results Per Page, default 20, max 100.
***
## Return format
A JSON array with keys:
- **followers_count** — Total number of followers.
- **followers_pages** — The total number of pages available in this resource.
- **page** — Number of the page currently being returned.
- **followers** — An indexed array of User objects in **[short format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The user requested has been disabled.
- **404 Not Found** — User does not exist in our database.
***
## Example
**Request**
GET v1/users/173/followers
**Return** __shortened for example purpose__
``` json
{
"followers_count": 7,
"followers_pages": 1,
"page": 1,
"followers": [
{
"id": 457180,
"username": "mgcirillo",
"firstname": "Mike",
"lastname": "Cirillo",
"city": "Toronto",
"country": "Canada",
"fullname": "Mike Cirillo",
"userpic_url": "http://acdn.500px.net/457180/bcbec7f69f5275d5ecf189bc05f07ab2560b2b22/1.jpg?0",
"upgrade_status": 2
},
{
"id": 12150,
"username": "MaksimPo",
"firstname": "Maksim",
"lastname": "p.",
"city": "tallinn",
"country": "estonia",
"fullname": "Maksim p.",
"userpic_url": "http://external.ak.fbcdn.net/safe_image.php?d=47fb0c08b05d512cf1afaa8866774b39&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-snc4%2F41765_100000921361830_4251_n.jpg&logo&v=5",
"upgrade_status": 0
},
{
"id": 2,
"username": "oleggutsol",
"firstname": "Oleg",
"lastname": "Gutsol",
"city": "Toronto",
"country": "Canada",
"fullname": "Oleg Gutsol",
"userpic_url": "http://acdn.500px.net/2/3aa7abe3aebc904c575c504e91fde4bb9f8baab9/1.jpg?11",
"upgrade_status": 2
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
================================================
FILE: endpoints/user/GET_users_id_friends.md
================================================
# User Resources
GET users/:id/friends
## Description
Returns a list of friends for the specified user.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **id** _(required)_ — Return information for the specified user ID
- **page** — Return the specified page of the resource. Page numbering is 1-based.
- **rpp** — Results Per Page, default 20, max 100.
***
## Return format
A JSON array with keys:
- **friends_count** — Total number of friends.
- **friends_pages** — The total number of pages available in this resource.
- **page** — Number of the page currently being returned.
- **friends** — An indexed array of User objects in **[short format][]**.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The user requested has been disabled.
- **404 Not Found** — User does not exist in our database.
***
## Example
**Request**
GET v1/users/173/friends
**Return** __shortened for example purpose__
```
{
"friends_count": 37,
"friends_pages": 2,
"page": 1,
"friends": [
{
"id": 457180,
"username": "mgcirillo",
"firstname": "Mike",
"lastname": "Cirillo",
"city": "Toronto",
"country": "Canada",
"fullname": "Mike Cirillo",
"userpic_url": "http://acdn.500px.net/457180/bcbec7f69f5275d5ecf189bc05f07ab2560b2b22/1.jpg?0",
"upgrade_status": 2
},
{
"id": 48920,
"username": "EvgueniTchebotarev",
"firstname": "Evgueni",
"lastname": "Tchebotarev",
"city": "Toronto",
"country": "Canada",
"fullname": "Evgueni Tchebotarev",
"userpic_url": "http://acdn.500px.net/48920.jpg",
"upgrade_status": 0
},
{
"id": 12150,
"username": "MaksimPo",
"firstname": "Maksim",
"lastname": "p.",
"city": "tallinn",
"country": "estonia",
"fullname": "Maksim p.",
"userpic_url": "http://external.ak.fbcdn.net/safe_image.php?d=47fb0c08b05d512cf1afaa8866774b39&url=http%3A%2F%2Fprofile.ak.fbcdn.net%2Fhprofile-ak-snc4%2F41765_100000921361830_4251_n.jpg&logo&v=5",
"upgrade_status": 0
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
================================================
FILE: endpoints/user/GET_users_search.md
================================================
# User Resources
GET users/search
## Description
Return listing of ten (up to one hundred) users from search results for a specified search term.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **term** _(required)_ — A keyword to search for.
***
## Return format
An array with the following keys and values:
- **current_page** — Number of the page that is returned.
- **total_pages** — Total number of pages in this feature's stream.
- **total_items** — Total number of items in this feature's stream.
- **users** — An array of Users objects in **[full format][]**.
***
## Errors
- **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
***
## Example
**Request**
GET v1/photos/search?term=vovko
**Return**
``` json
{
"current_page": 1,
"total_pages": 1,
"total_items": 1,
"users": [
{
"id": 173,
"username": "vovko",
"firstname": "Vladimir",
"lastname": "Drizhepolov",
"birthday": null,
"sex": 1,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"registration_date": "2009-11-08T12:41:14-05:00",
"about": "Toronto based photographer.\r\n",
"domain": "vovko.500px.com",
"fotomoto_on": true,
"locale": "en",
"show_nude": true,
"fullname": "Vladimir Drizhepolov",
"userpic_url": "http://acdn.500px.net/173.jpg",
"upgrade_status": 2,
"store_on": true,
"contacts": {
"website": "vovko.ca",
"twitter": "vovko",
"flickr": "Vladimir Drizhepolov",
"gtalk": "vladimir@drizhepolov.com",
"facebook": "562874260",
"blog": "www.vovko.ca"
},
"equipment": {
"camera": [
"Kiev 88"
],
"lens": [
"Volna 80mm"
]
},
"photos_count": 17,
"affection": 4,
"friends_count": 86,
"followers_count": 18,
"following": false
}
]
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/user/GET_users_show.md
================================================
# User Resources
GET users/show
## Description
Returns the profile information for a specified user.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
(required) One of the unique user identifiers:
- **id** — Return information for the specified user ID.
- **username** — Return information for the user with the specified username.
- **email** — Return information for the user with the specified email address.
***
## Return format
User profile information in **[full format][]**.
Additional data:
- **following** — (OAuth only) whether the currently authenticated user is following the user specified by the identifier, boolean.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error. Some results also include 'lookup_method' key specifying the parameter that was used for user lookup.
- **400 Bad Request** — Request did not contain one of the required parameters.
- **403 Forbidden** — The user requested has been disabled.
- **404 Not Found** — User does not exist in our database.
***
## Example
**Request (Using OAuth)**
GET v1/users/show?username=freeatnet
**Return**
``` json
{
"user": {
"id": 3798,
"username": "freeatnet",
"firstname": "Arseniy",
"lastname": "Ivanov",
"birthday": null,
"sex": 1,
"city": "Toronto",
"state": "Ontario",
"country": "Canada",
"registration_date": "2009-12-15T09:40:45-05:00",
"about": "Your local web-developer guy. Casual photographer.",
"domain": "freeatnet.500px.com",
"fotomoto_on": true,
"locale": "en",
"show_nude": true,
"fullname": "Arseniy Ivanov",
"userpic_url": "/graphics/userpic.png",
"upgrade_status": 2,
"store_on": true,
"contacts": {
"website": "freeatnet.com",
"twitter": "freeatnet_en",
"facebookpage": "www.facebook.com/av.ivanov",
"flickr": "freeatnet",
"facebook": "769184274"
},
"equipment": {
"camera": [
"FUJIFILM FinePix S1000",
"Canon EOS 50"
],
"misc": [
"Google Nexus S",
"Apple Macbook Pro 15\""
]
},
"photos_count": 12,
"galleries_count": 5,
"affection": 20,
"friends_count": 57,
"followers_count": 77,
"following": false
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format
================================================
FILE: endpoints/user/POST_users_id_friends.md
================================================
# User Resources
POST users/:id/friends
## Description
Add the user to the list of followers.
***
## Requires authentication
* A valid Consumer Key must be provided in **consumer_key** parameter.
* Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
***
## Parameters
- **id** _(required)_ — ID of the User to add to the followers list.
***
## Return format
A JSON array with followed User object.
***
## Errors
All known errors cause the resource to return HTTP error code header together with a JSON array containing at least 'status' and 'error' keys describing the source of error.
- **403 Forbidden** — The user requested has been disabled or already in followers list.
- **404 Not Found** — User does not exist in our database.
***
## Example
**Request**
POST v1/users/827595/friends
**Return**
``` json
{
user: {
id: 827595,
username: "voldemarpetruskauskus",
firstname: "Voldemar",
lastname: "Petruskauskus",
birthday: null,
sex: 0,
city: "",
state: "",
country: "",
registration_date: "2012-05-15T11:19:42-04:00",
about: "Voldemar",
domain: null,
upgrade_status: 9,
fotomoto_on: false,
locale: "en",
show_nude: false,
store_on: false,
contacts: { },
equipment: { }
}
}
```
[OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
[short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
================================================
FILE: examples/PHP/PHP.md
================================================
# PHP
There is an extensive wiki on of OAuth and xAuth authentication over at [oauth-php-wiki][] on Google Code. 500px.com oAuth is actually quite similar to Twitter's. Appropriating [@abraham's][] [TwitterOAuth][] library will give you a head start.
In <code>lib/TwitterOAuth.php</code> make the following adjustments:
$host = 'https://api.500px.com/v1/';
And set up the URLs:
/* Set API URLS */
function accessTokenURL() { return 'https://api.500px.com/v1/oauth/access_token'; }
function authenticateURL() { return 'https://api.500px.com/v1/oauth/authorize'; }
function authorizeURL() { return 'https://api.500px.com/v1/oauth/authorize'; }
function requestTokenURL() { return 'https://api.500px.com/v1/oauth/request_token'; }
Change the example index.php from:
/* If method is set change API call made. Test is called by default. */
#$content = $connection->get('account/verify_credentials');
To:
/* Retrieve all photos in category Journalism that were uploaded today */
$content = $connection->get('photos', array('feature' => 'fresh_today', 'only' => 'Journalism'));
[oauth-php-wiki]: http://example.com/ "OAuth - Consumer and Server library for PHP"
[@abraham's]: http://twitter.com/abraham "@abraham"
[twitteroauth]: https://github.com/abraham/twitteroauth "TwitterOAuth"
================================================
FILE: examples/Ruby/xauth.rb
================================================
require 'rubygems'
require 'oauth'
require 'multi_json'
CONSUMER_KEY = ''
CONSUMER_SECRET = ''
USERNAME = ''
PASSWORD = ''
BASE_URL = 'https://api.500px.com'
def get_access_token
p "get_access_token: Initializing Consumer"
consumer = OAuth::Consumer.new(CONSUMER_KEY, CONSUMER_SECRET, {
:site => BASE_URL,
:request_token_path => "/v1/oauth/request_token",
:access_token_path => "/v1/oauth/access_token",
:authorize_path => "/v1/oauth/authorize"})
request_token = consumer.get_request_token()
p "Request URL: #{request_token.authorize_url}"
access_token = consumer.get_access_token(request_token, {}, { :x_auth_mode => 'client_auth', :x_auth_username => USERNAME, :x_auth_password => PASSWORD })
access_token
end
access_token = get_access_token
p "token: #{access_token.token}"
p "secret: #{access_token.secret}"
#p access_token.get('/v1/photos.json').body
p MultiJson.decode(access_token.get('/v1/users.json').body).inspect
================================================
FILE: examples/iOS/API Tutorials.md
================================================
# 500px API Tutorial
Hello astronauts, war heroes, Olympians - you're here because we want the best, and you are it. So: Who is ready to make some great apps?
## Specifics
500px API requests are RESTful and return JSON. **All** 500px API requests are conducted over HTTPS. There are two ways to sign requests: Consumer Key and OAuth. Consumer Key-signed requests are ones that aren't specific to a logged-in user. For instance, getting a list of popular photos only requires the Consumer Key authentication. However, liking a photo requires a user to be logged in; these types of requests must be signed with OAuth.
There are some requests which can be signed with either a Consumer Key or OAuth. In these cases, additional information is returned if the request is signed with OAuth. This information is specific to the currently logged-in user; for example, whether or not a user has liked a photo or is following a specific user.
## Signing Requests with your Consumer Key
To sign a request with your consumer key, all you have to do append `consumer_key=YOUR_CONSUMER_KEY_HERE` to the query string of the request. So a request to look at the second page of editor's choice would look `https://api.500px.com/v1/photos?feature=editors&page=2&consumer_key=YOUR_CONSUMER_KEY_HERE`.
## Signing Requests with OAuth
Signing requests with OAuth is, unsurprisingly, more complicated. First off, you'll need to authenticate your user.
### Three-Legged OAuth Authentication
The three-legged OAuth authentication with the 500px API is straightforward and uses standard OAuth workflow. Any one of available libraries for your platform should work. If you want to roll your own, the instructions below on two-legged OAuth should get you going.
### Two-Legged OAuth Authentication
Two-legged OAuth authentication, sometimes referred to as XAuth, is also possible if we enabled it on your account. Just ask nicely :)
1. ### Obtain a request token.
Make a POST request to `https://api.500px.com/v1/oauth/request_token`. Set the HTTP header "Authorization" to the same URL. You should receive back a 200 response code and a string like the following.
> oauth_token=TOKEN_HERE&oauth_token_secret=SECRET_HERE&oauth_callback_confirmed=true
Extract these out for the next step.
2. ### Obtain Access Token
Make a POST request to `https://api.500px.com/v1/oauth/access_token`. You'll need to set the POST body to be a querey string containing `x_auth_mode` set to "client_auth" and `x_auth_password` and `x_auth_username` set to URL-encoded username and password with which you're trying to authenticate. These keys/value pairs must be lexicographically sorted by key name. In Objective-C, this looks something like the following:
NSArray * parameterArray = [NSArray arrayWithObjects:
[NSString stringWithFormat:@"%@=%@", @"x_auth_mode", @"client_auth"],
[NSString stringWithFormat:@"%@=%@", @"x_auth_password", [thePassword urlEncode]],
[NSString stringWithFormat:@"%@=%@", @"x_auth_username", [theUserName urlEncode]], nil];
[postRequest setHTTPBody:[[parameterArray componentsJoinedByString:@"&"] dataUsingEncoding:NSUTF8StringEncoding]];
This is the easy part. Now we need to set the `Authorization` HTTP header. We use the `oauth_nonce`, `oauth_signature_method`, `oauth_timestamp`, `oauth_consumer_key`, `oauth_token`, `oauth_signature`, and `oauth_version` parameters to construct the OAuth `Authorization` field value. The order of these is again **very important** since they are lexicographically sorted by key name. In Objective-C, it is constructed as follows:
NSArray * keysAndValues = [NSArray arrayWithObjects:
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_nonce", [self.nonce urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature_method", [@"HMAC-SHA1" urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_timestamp", [self.timestamp urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_consumer_key", [kConsumerKey urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_token", [theRequestToken urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature", [SIGNATURE_HERE urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_version", [[NSString stringWithString:@"1.0"] urlEncode]],
nil];
[postRequest addValue:[NSString stringWithFormat:@"OAuth %@", [keysAndValues componentsJoinedByString:@", "] forHTTPHeaderField:@"Authorization"];
One of the key/value pairs we use here is the signature used by OAuth. *This uses a different base string than the one used to sign normal OAuth requests*. This special base string is constructed and then encrypted using HMAC-SHA1.
Append your request secret to you Consumer Secret, separated by an apersand, and encode it with UTF8. Construct your base string (see below) and encode it with UTF8 as well, and then generate the signature. In Objective-C, a method to generate this might look like the following:
NSString * secret = [NSString stringWithFormat:@"%@&%@", YOUR_CONSUMER_KEY_HERE, theRequestSecret];
NSData * secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
NSData * baseData = [BASE_STRING_HERE dataUsingEncoding:NSUTF8StringEncoding];
uint8_t digest[20] = {0};
CCHmac(kCCHmacAlgSHA1, secretData.bytes, secretData.length,
baseData.bytes, baseData.length, digest);
NSData * signatureData = [NSData dataWithBytes:digest length:20];
return [signatureData base64EncodedString];
Lastly, we'll need to construct the base string used to create the signature. This is farily straightforward but is a little quirky. Constructing the base string in Objective-C would look like the following:
NSString * url = [theURL urlEncode]; //this is the URL we're calling, should be https://api.500px.com/v1/oauth/access_token
NSString * parameters;
NSString * oauth_consumer_key = [YOUR_CONSUMER_KEY urlEncode];
NSString * oauth_nonce = [self.nonce urlEncode];
NSString * oauth_signature_method = [[NSString stringWithString:@"HMAC-SHA1"] urlEncode];
NSString * oauth_timestamp = [self.timestamp urlEncode];
NSString * oauth_version = [[NSString stringWithString:@"1.0"] urlEncode];
NSString * x_auth_mode = [@"client_auth" urlEncode];
NSString * x_auth_password = [[thePassword urlEncode] urlEncode]; //These are double-encoded on purpose
NSString * x_auth_username = [[theUserName urlEncode] urlEncode];
NSArray * params = [NSArray arrayWithObjects:
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_consumer_key", oauth_consumer_key],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_nonce", oauth_nonce],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_signature_method", oauth_signature_method],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_timestamp", oauth_timestamp],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_token", theRequestToken],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_version", oauth_version],
nil];
params = [params arrayByAddingObjectsFromArray:[NSArray arrayWithObjects:[NSString stringWithFormat:@"%@%%3D%@", @"x_auth_mode", x_auth_mode],
[NSString stringWithFormat:@"%@%%3D%@", @"x_auth_password", x_auth_password],
[NSString stringWithFormat:@"%@%%3D%@", @"x_auth_username", x_auth_username], nil]];
//sort paramaters lexicographically
params = [params sortedArrayUsingSelector:@selector(compare:)];
parameters = [params componentsJoinedByString:@"%26"];
NSArray * baseComponents = [NSArray arrayWithObjects:
theHTTPMethod,
url,
parameters,
nil];
NSString * baseString = [baseComponents componentsJoinedByString:@"&"];
And that's it. If all goes well, you should get back a 200 response code with a response body resembling `oauth_token=THE_TOKEN&oauth_token_secret=THE_SECRET`. Of course, things don't always go well. You may receive a 403 if the user enters invalid credentials; you can also get "`Invalid OAuth Request`" if something is wrong with your signing code.
## Signing Requests
At a high-level, signing requests is just adding a special value for the `Authorization` HTTP header field. The POST request looks something like this:
The process to create this request is represented in the following flow chart.
Signing requests with OAuth involves creating a special value for the `Authorization` HTTP header field. Creating that header value requires the HTTP method (POST, GET, or DELETE), the POST or GET parameters you're sending, and the token/secret combination you obtained when the user was authenticated (above).
The value of the `Authorization` HTTP header field is:
OAuth SORTED_KEY_VALUE_PAIRS_HERE.
The list of key/value pairs are sorted lexicographically and include `oauth_none`, `outh_signature_method`, `oauth_timestamp`, `oauth_consumer_key`, `oauth_token`, `oauth_signature`, and `oauth_version`. In Objective-C, a method to create this string would resmble the following:
NSArray * keysAndValues = [NSArray arrayWithObjects:
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_consumer_key", [kConsumerKey urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_nonce", [self.nonce urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature", [YOUR_SIGNATURE_HERE urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature_method", [[NSString stringWithString:@"HMAC-SHA1"] urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_timestamp", [self.timestamp urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_token", [theToken urlEncode]],
[NSString stringWithFormat:@"%@=\"%@\"", @"oauth_version", [[NSString stringWithString:@"1.0"] urlEncode]], nil];
return [NSString stringWithFormat:@"OAuth %@", [keysAndValues componentsJoinedByString:@", "]];
You'll need to construct a signature for this request. This is a **different but similar** signature than the one used in authentication. The signature is encrypted using the consumer secret and access secret using HMAC-SHA1. An Objective-C method to encrypt a base string, yielding a signature, would look like the following:
NSString * secret = [NSString stringWithFormat:@"%@&%@", kConsumerSecret, theSecret];
NSData * secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
NSData * baseData = [YOUR_BASE_STRING_HERE dataUsingEncoding:NSUTF8StringEncoding];
uint8_t digest[20] = {0};
CCHmac(kCCHmacAlgSHA1, secretData.bytes, secretData.length,
baseData.bytes, baseData.length, digest);
NSData * signatureData = [NSData dataWithBytes:digest length:20];
return [signatureData base64EncodedString];
The base string, similar but different to the one used in authentication, is constructed by concatenating the sorted list of `oauth_consumer_key`, `oauth_nonce`, `oauth_signature_method`, `oauth_timestamp`, `oauth_token`, and `oauth_version`, as well as any POST or GET parameters. The keys and values of the POST or GET parameters, in addition to the values for the OAuth parameters, must be URL-encoded. An Objective-C method to construct the base string would look like the following:
NSString * url = [theURL urlEncode];
NSString * parameters;
NSString * oauth_consumer_key = [kConsumerKey urlEncode];
NSString * oauth_nonce = [self.nonce urlEncode];
NSString * oauth_signature_method = [[NSString stringWithString:@"HMAC-SHA1"] urlEncode];
NSString * oauth_timestamp = [self.timestamp urlEncode];
NSString * oauth_version = [[NSString stringWithString:@"1.0"] urlEncode];
NSArray * params = [NSArray arrayWithObjects:
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_consumer_key", oauth_consumer_key],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_nonce", oauth_nonce],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_signature_method", oauth_signature_method],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_timestamp", oauth_timestamp],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_token", theToken],
[NSString stringWithFormat:@"%@%%3D%@", @"oauth_version", oauth_version],
nil];
NSArray *keys = [theOptions allKeys];
for (id key in keys)
{
params = [params arrayByAddingObject:[[NSString stringWithFormat:@"%@=%@", [key urlEncode], [[theOptions valueForKey:key] urlEncode]] urlEncode]];
}
//sort paramaters lexicographically
params = [params sortedArrayUsingSelector:@selector(compare:)];
parameters = [params componentsJoinedByString:@"%26"];
NSArray * baseComponents = [NSArray arrayWithObjects:
theHTTPMethod,
url, //The URL you're requesting, *not* including any GET parameters
parameters,
nil];
NSString * baseString = [baseComponents componentsJoinedByString:@"&"];
### POST
POST parameters need to have their key and value individually URL-encoded. Sort the parameters list lexicographically and concatenate them as a query string, separated by ampersands, and encode the string with UTF8 as the POST HTTP body.
### GET
GET parameters are added to the end of URLs. They should not be URL-encoded, but *do* need to be lexicographically sorted.
### DELETE
Whenever you want to DELETE an item, send a POST request instead with `_method` parameter set to "`delete`".
## Photo Streams
Photo streams include Popular, Editor's Choice, Upcoming, Fresh (variants include today, yesterday, and this week), a user's feed, and a user's friend feed.
Photo Streams are a GET request that can be signed either with your Consumer Key or OAuth. If you sign with OAuth, the response will indicate if the currently logged in user has voted for each photo.
Specifying specific users (`user` or `user_friends` features) requires either specifying a `user_id` or `username` parameter.
Photo streams can be sorted into only displaying one category, excluding a category, and sorting the results. You can specify a pagination values for page number and results per page. Excluding categories with spaces, like "Black and White" uses the string "Black+and+White" as a value for the `exclude` key.
Photo streams return a JSON dictionary containing the current page, the feature, any filters, the total number of items in the feed, and the total pages in the feed (using the same results per page as specified in the request). Finally, there is an array called `photos` that contains the photos in the stream in short-form (see below).
Optionally, you may specify an `image_size` parameter to specify the size of the thumbnail contained in each short-form photo model.
<table>
<tr><th>image_size</th><th>Thumbnail Sizes</th></tr>
<tr><td>1</td><td>70 x 70</td></tr>
<tr><td>2</td><td>140 x 140</td></tr>
<tr><td>3</td><td>280 x 280</td></tr>
<tr><td>4</td><td>900 wide or 900 tall, max</td></tr>
</table>
Please specify an `image_size` that is appropriate for your app; it will help your user experience and reduce our bandwidth costs! If the photographer has uploaded a smaller image to 500px, then we do *not* scale that image up to 900px.
## Search
The search API currently only searches *photos*, not *users*. You can specify either a search `term` or `tag` (exactly one is required). You can also specify pagination information which includes the page number and results per page.
Returned JSON is in the same format as the photo stream response.
## Specific Photo Details
This endpoint returns a long-form photo model and a `comments` array. You can specify pagination data for the comments with `comments_page` (comment pages always contain 20 comments or fewer).
## Liking Photos
Our API only allows users to vote *for* photos; it doesn't allow them to downvote.
To like a photo, POST to the `photos/PHOTO_ID/vote` endpoint with the parameter `vote` set to `1`. This method **must** be signed with OAuth.
To undo a like on a photo, DELETE to the `photos/PHOTO_ID/vote` endpoint. This method **must** be signed with OAuth.
Your response includes, in part, a short-form photo model; this model's rating has been updated to reflect your user's like (or unlike).
### Following/Unfollowing Users
To follow or unfollow a user, either POST or DELETE to the `users/USER_ID/friends` endpoint. You can only do this for the currently logged-in user. If the response code is non-200, an `error` key/value pair will specify what went wrong. Common `error` values are "Already following" and "Your're following too many users". Currently, the number of users you can follow is capped to ~4000.
## Uploading Photos
To upload a photo, you nee
gitextract_xgnx4pl1/
├── .gitignore
├── .gitmodules
├── 500px-api.xml
├── README.md
├── authentication/
│ ├── POST_oauth_accesstoken.md
│ ├── POST_oauth_authorize.md
│ ├── POST_oauth_requesttoken.md
│ └── upload_key.md
├── basics/
│ ├── formats_and_terms.md
│ ├── terms_of_use.md
│ └── upload.md
├── endpoints/
│ ├── collections/
│ │ ├── DELETE_collections_id.md
│ │ ├── GET_collections.md
│ │ ├── GET_collections_id.md
│ │ ├── POST_collections.md
│ │ └── PUT_collections_id.md
│ ├── comments/
│ │ └── POST_comments_id_comments.md
│ ├── galleries/
│ │ ├── DELETE_galleries_id.md
│ │ ├── GET_galleries.md
│ │ ├── GET_galleries_id.md
│ │ ├── GET_galleries_id_items.md
│ │ ├── GET_galleries_id_share_url.md
│ │ ├── POST_galleries.md
│ │ ├── PUT_galleries_id.md
│ │ ├── PUT_galleries_id_items.md
│ │ └── PUT_galleries_reposition.md
│ ├── photo/
│ │ ├── DELETE_photos_id.md
│ │ ├── DELETE_photos_id_tags.md
│ │ ├── DELETE_photos_id_vote.md
│ │ ├── GET_photos.md
│ │ ├── GET_photos_id.md
│ │ ├── GET_photos_id_comments.md
│ │ ├── GET_photos_id_votes.md
│ │ ├── GET_photos_search.md
│ │ ├── POST_photos.md
│ │ ├── POST_photos_id_comments.md
│ │ ├── POST_photos_id_report.md
│ │ ├── POST_photos_id_tags.md
│ │ ├── POST_photos_id_vote.md
│ │ └── PUT_photos_id.md
│ ├── template.md
│ └── user/
│ ├── DELETE_users_id_friends.md
│ ├── GET_users.md
│ ├── GET_users_id_followers.md
│ ├── GET_users_id_friends.md
│ ├── GET_users_search.md
│ ├── GET_users_show.md
│ └── POST_users_id_friends.md
└── examples/
├── PHP/
│ └── PHP.md
├── Ruby/
│ └── xauth.rb
└── iOS/
└── API Tutorials.md
SYMBOL INDEX (1 symbols across 1 files) FILE: examples/Ruby/xauth.rb function get_access_token (line 12) | def get_access_token
Condensed preview — 51 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (214K chars).
[
{
"path": ".gitignore",
"chars": 10,
"preview": ".DS_Store\n"
},
{
"path": ".gitmodules",
"chars": 438,
"preview": "[submodule \"examples/python-sdk\"]\n\tpath = examples/python-sdk\n\turl = git@github.com:500px/PxMagic.git\n[submodule \"exampl"
},
{
"path": "500px-api.xml",
"chars": 22183,
"preview": "\n<application xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n\txmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"\n\txmlns"
},
{
"path": "README.md",
"chars": 9547,
"preview": "# 500px API\n\n500px API provides programmatic access to 500px functionality and content.\nVersion 1 of the API is limited "
},
{
"path": "authentication/POST_oauth_accesstoken.md",
"chars": 1748,
"preview": "# OAuth\n\n POST oauth/access_token\n\n## Description\nAllows a Consumer application to exchange an OAuth Request Token fo"
},
{
"path": "authentication/POST_oauth_authorize.md",
"chars": 1768,
"preview": "# OAuth\n\n POST oauth/authorize\n\n## Description\nAllows a Consumer application to obtain user authorization for an OAut"
},
{
"path": "authentication/POST_oauth_requesttoken.md",
"chars": 1096,
"preview": "# OAuth\n\n POST oauth/request_token\n\n## Description\nAllows a Consumer application to obtain an OAuth Request Token to "
},
{
"path": "authentication/upload_key.md",
"chars": 1283,
"preview": "# Upload key authorization\n\nOAuth does not support encoding multipart/form-data messages. As such, it is impossible to s"
},
{
"path": "basics/formats_and_terms.md",
"chars": 21875,
"preview": "# Formats and Terms\n\n[500px.com][] allows discovery of the photography uploaded by users in a\nnumber of ways. An essenti"
},
{
"path": "basics/terms_of_use.md",
"chars": 20859,
"preview": "# Terms of Use\n\nThis agreement sets out the terms and conditions (the \"API Terms of Use\") pursuant to which you are lice"
},
{
"path": "basics/upload.md",
"chars": 2487,
"preview": "# Uploading a photo\nTo upload a photo, you need to do 2 requests:\n 1. `POST /photos`\n 1. `POST url-obtained-from-first-r"
},
{
"path": "endpoints/collections/DELETE_collections_id.md",
"chars": 778,
"preview": "### DEPRECATED\n\nPlease use the corresponding **[galleries endpoint][]**\n\n***\n\n# Collections Resources\n\n DELETE collec"
},
{
"path": "endpoints/collections/GET_collections.md",
"chars": 2337,
"preview": "### DEPRECATED\n\nPlease use the corresponding **[galleries endpoint][]**\n\n***\n\n# Collections Resources\n\n GET collectio"
},
{
"path": "endpoints/collections/GET_collections_id.md",
"chars": 2236,
"preview": "### DEPRECATED\n\nPlease use the corresponding **[galleries endpoint][]**\n\n***\n\n# Collections Resources\n\n GET collectio"
},
{
"path": "endpoints/collections/POST_collections.md",
"chars": 1635,
"preview": "### DEPRECATED\n\nPlease use the corresponding **[galleries endpoint][]**\n\n***\n\n# Collections Resources\n\n POST collecti"
},
{
"path": "endpoints/collections/PUT_collections_id.md",
"chars": 1792,
"preview": "### DEPRECATED\n\nPlease use the corresponding **[galleries endpoint][]**\n\n***\n\n# Collections Resources\n\n PUT collectio"
},
{
"path": "endpoints/comments/POST_comments_id_comments.md",
"chars": 1903,
"preview": "# Comment Resources\n\n POST comments/:id/comments\n\n## Description\nCreates a reply to an existing comment. Comments can"
},
{
"path": "endpoints/galleries/DELETE_galleries_id.md",
"chars": 805,
"preview": "# Galleries Resources\n\n DELETE users/:user_id/galleries/:id\n\n## Description\n\nDeletes the gallery.\n\n***\n\n## Requires a"
},
{
"path": "endpoints/galleries/GET_galleries.md",
"chars": 2958,
"preview": "# Galleries Resources\n\n GET users/:user_id/galleries\n\n## Description\n\nReturns a listing of twenty (up to one hundred)"
},
{
"path": "endpoints/galleries/GET_galleries_id.md",
"chars": 1352,
"preview": "# Galleries Resources\n\n GET users/:user_id/galleries/:id\n\n## Description\n\nReturns the details of the requested galler"
},
{
"path": "endpoints/galleries/GET_galleries_id_items.md",
"chars": 4457,
"preview": "# Galleries Resources\n\n GET users/:user_id/galleries/:id/items\n\n## Description\n\nReturns a listing of twenty (up to on"
},
{
"path": "endpoints/galleries/GET_galleries_id_share_url.md",
"chars": 708,
"preview": "# Galleries Resources\n\n```\nGET users/:user_id/galleries/:id/share_url\n```\n\n# Description\n\nReturns a sharable private URL"
},
{
"path": "endpoints/galleries/POST_galleries.md",
"chars": 1482,
"preview": "# Galleries Resources\n\n POST users/:user_id/galleries\n\n## Description\n\nCreates a new, empty gallery owned by the give"
},
{
"path": "endpoints/galleries/PUT_galleries_id.md",
"chars": 1477,
"preview": "# Galleries Resources\n\n PUT users/:user_id/galleries/:id\n\n## Description\n\nUpdates the metadata for the given gallery."
},
{
"path": "endpoints/galleries/PUT_galleries_id_items.md",
"chars": 3379,
"preview": "# Galleries Resources\n\n PUT users/:user_id/galleries/:id/items\n\n## Description\n\nAdds, removes, or updates the order o"
},
{
"path": "endpoints/galleries/PUT_galleries_reposition.md",
"chars": 1552,
"preview": "# Galleries Resources\n\n PUT users/:user_id/galleries/reposition\n\n## Description\n\nBulk repositions galleries. Accepts"
},
{
"path": "endpoints/photo/DELETE_photos_id.md",
"chars": 913,
"preview": "# Photo Resources\n\n DELETE photos/:id\n\n## Description\nDeletes the photo from the User's library.\n\n***\n\n## Requires au"
},
{
"path": "endpoints/photo/DELETE_photos_id_tags.md",
"chars": 944,
"preview": "# Photo Resources\n\n DELETE photos/:id/tags\n\n## Description\nRemoves tags from the photo. Accepts one or multiple coma "
},
{
"path": "endpoints/photo/DELETE_photos_id_vote.md",
"chars": 1077,
"preview": "# Photo Resources\n\n DELETE photos/:photo_id/vote\n\n## Description\nUnlikes the specified photo for the user.\n\n***\n\n## R"
},
{
"path": "endpoints/photo/GET_photos.md",
"chars": 7757,
"preview": "# Photo Resources\n\n GET photos\n\n## Description\nReturns a listing of twenty (up to one hundred) photos for a specified"
},
{
"path": "endpoints/photo/GET_photos_id.md",
"chars": 5057,
"preview": "# Photo Resources\n\n GET photos/:id\n\n## Description\nReturns detailed information of a single photo.\n\n***\n\n## Requires "
},
{
"path": "endpoints/photo/GET_photos_id_comments.md",
"chars": 3856,
"preview": "# Comment Resources\n\n GET photos/:id/comments\n\n## Description\nReturns a listing of twenty comments for the photo.\n\n**"
},
{
"path": "endpoints/photo/GET_photos_id_votes.md",
"chars": 2578,
"preview": "# Photo Resources\n\n GET photos/:id/votes\n\n## Description\nReturns all users that had liked this photo.\n\n***\n\n## Requir"
},
{
"path": "endpoints/photo/GET_photos_search.md",
"chars": 5585,
"preview": "# Photo Resources\n\n GET photos/search\n\n## Description\nReturns a listing of twenty (up to one hundred) photos from sea"
},
{
"path": "endpoints/photo/POST_photos.md",
"chars": 4133,
"preview": "# Photo Resources\n\n POST photos\n\n## Description\nCreate a new photo on behalf of the user, and receive an **[upload ke"
},
{
"path": "endpoints/photo/POST_photos_id_comments.md",
"chars": 1753,
"preview": "# Photo Resources\n\n POST photos/:id/comments\n\n## Description\nCreates a new comment for the photo.\n\n***\n\n## Requires a"
},
{
"path": "endpoints/photo/POST_photos_id_report.md",
"chars": 1179,
"preview": "# Photo Resources\n\n POST photos/:id/report\n\n## Description\nAllows to report a photo.\n\n***\n\n## Parameters\n\n- **id** _("
},
{
"path": "endpoints/photo/POST_photos_id_tags.md",
"chars": 942,
"preview": "# Photo Resources\n\n POST photos/:id/tags\n\n## Description\nAdds tags to the photo. Accepts one or multiple coma separat"
},
{
"path": "endpoints/photo/POST_photos_id_vote.md",
"chars": 2502,
"preview": "# Photo Resources\n\n POST photos/:id/vote\n\n## Description\nAllows the user to vote for a photo.\n\n***\n\n## Requires authe"
},
{
"path": "endpoints/photo/PUT_photos_id.md",
"chars": 5700,
"preview": "# Updating a Photo's Information\n\n PUT photos/:id\n\n## Description\n\nAllows the client application to update user-edita"
},
{
"path": "endpoints/template.md",
"chars": 751,
"preview": "# Photo Resources\n\n GET example/:id\n\n## Description\n\n***\n\n## Requires authentication\n\n***\n\n## Parameters\n\n***\n\n## Ret"
},
{
"path": "endpoints/user/DELETE_users_id_friends.md",
"chars": 1536,
"preview": "# User Resources\n\n DELETE users/:id/friends\n\n## Description\nRemoves the user from the list of followers.\n\n***\n\n## Req"
},
{
"path": "endpoints/user/GET_users.md",
"chars": 2403,
"preview": "# User Resources\n\n GET users\n\n## Description\nReturns the profile information for the current user.\n\n***\n\n## Requires "
},
{
"path": "endpoints/user/GET_users_id_followers.md",
"chars": 2621,
"preview": "# User Resources\n\n GET users/:id/followers\n\n## Description\nReturns a list of users who follow the specified user.\n\n**"
},
{
"path": "endpoints/user/GET_users_id_friends.md",
"chars": 2607,
"preview": "# User Resources\n\n GET users/:id/friends\n\n## Description\nReturns a list of friends for the specified user.\n\n***\n\n## R"
},
{
"path": "endpoints/user/GET_users_search.md",
"chars": 2364,
"preview": "# User Resources\n\n GET users/search\n\n## Description\nReturn listing of ten (up to one hundred) users from search resul"
},
{
"path": "endpoints/user/GET_users_show.md",
"chars": 2725,
"preview": "# User Resources\n\n GET users/show\n\n## Description\nReturns the profile information for a specified user.\n\n***\n\n## Requ"
},
{
"path": "endpoints/user/POST_users_id_friends.md",
"chars": 1522,
"preview": "# User Resources\n\n POST users/:id/friends\n\n## Description\nAdd the user to the list of followers.\n\n***\n\n## Requires au"
},
{
"path": "examples/PHP/PHP.md",
"chars": 1338,
"preview": "# PHP\n\nThere is an extensive wiki on of OAuth and xAuth authentication over at [oauth-php-wiki][] on Google Code. 500px."
},
{
"path": "examples/Ruby/xauth.rb",
"chars": 972,
"preview": "require 'rubygems'\nrequire 'oauth'\nrequire 'multi_json'\n\nCONSUMER_KEY = ''\nCONSUMER_SECRET = ''\nUSERNAME = ''\nPASSWORD ="
},
{
"path": "examples/iOS/API Tutorials.md",
"chars": 24746,
"preview": "# 500px API Tutorial\n\nHello astronauts, war heroes, Olympians - you're here because we want the best, and you are it. So"
}
]
About this extraction
This page contains the full source code of the 500px/api-documentation GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 51 files (195.0 KB), approximately 53.5k tokens, and a symbol index with 1 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.