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 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, 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

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:

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

***

License Types

500px currently supports these types of licenses, more details can be found at https://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

Gallery kinds

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.

_{* Can only contain photos uploaded by the gallery owner}

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 (https://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

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 (https://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: 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.

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
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"
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!