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:
- 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
- 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’s Photos, all active public photos of a given user
- User’s Friends’ Photos, a collection of User’s Photos streams from all followings of a given user
- Editors’ Choice, photos selected by 500px.com Editors, cached indefinitely
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:
| ID | Dimensions |
|---|---|
| 1 | 70px x 70px |
| 2 | 140px x 140px |
| 3 | 280px x 280px |
| 100 | 100px x 100px |
| 200 | 200px x 200px |
| 440 | 440px x 440px |
| 600 | 600px x 600px |
These are the standard uncropped sizes:
| ID | Dimensions |
|---|---|
| 4 | 900px on the longest edge |
| 5 | 1170px on the longest edge |
| 6 | 1080px high |
| 20 | 300px high |
| 21 | 600px high |
| 30 | 256px on the longest edge |
| 31 | 450px high |
| 1080 | 1080px on the longest edge |
| 1600 | 1600px on the longest edge |
| 2048 | 2048px on the longest edge |
Categories of photos may be specified by their ID or string name, depending on the API method.
| ID | Category |
|---|---|
| 0 | Uncategorized |
| 10 | Abstract |
| 29 | Aerial New! |
| 11 | Animals |
| 5 | Black and White |
| 1 | Celebrities |
| 9 | City and Architecture |
| 15 | Commercial |
| 16 | Concert |
| 20 | Family |
| 14 | Fashion |
| 2 | Film |
| 24 | Fine Art |
| 23 | Food |
| 3 | Journalism |
| 8 | Landscapes |
| 12 | Macro |
| 18 | Nature |
| 30 | Night New! |
| 4 | Nude |
| 7 | People |
| 19 | Performing Arts |
| 17 | Sport |
| 6 | Still Life |
| 21 | Street |
| 26 | Transportation New! |
| 13 | Travel |
| 22 | Underwater |
| 27 | Urban Exploration New! |
| 25 | Wedding New! |
500px currently supports these types of licenses, more details can be found at http://500px.com/creativecommons
| ID | License Type |
|---|---|
| 0 | Standard 500px License |
| 1 | Creative Commons License Non Commercial Attribution |
| 2 | Creative Commons License Non Commercial No Derivatives |
| 3 | Creative Commons License Non Commercial Share Alike |
| 4 | Creative Commons License Attribution |
| 5 | Creative Commons License No Derivatives |
| 6 | Creative Commons License Share Alike |
| 7 | Creative Commons License Public Domain Mark 1.0 |
| 8 | Creative Commons License Public Domain Dedication |
| ID | Gallery Kinds | Contents |
|---|---|---|
| 0 | General | Any photo on 500px |
| 1 | Lightbox | Marketplace photos |
| 3 | Portfolio* | Photos displayed on the portfolio page |
| 4 | Profile* | Photos uploaded by the gallery owner |
| 5 | Favorite | Photos favorited by the gallery owner via the old API. |
Categories of photos may be specified by their ID or string name, depending on the API method.
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
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
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.
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:
en, ru, de, ja, br, es. - 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
camera, lens, misc. 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
default, large, small, tiny. 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
facebook, twitter, google_oauth2. 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.
The profile format of a User object includes the following data:
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.
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
- user (optional) - User who owns the gallery, in short 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
- 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"
}
- 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"
}