Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
439 lines (378 sloc) 21.6 KB

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:

Special streams:


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
170px x 70px
2140px x 140px
3280px x 280px
100100px x 100px
200200px x 200px
440440px x 440px
600600px x 600px

These are the standard uncropped sizes:

ID Dimensions
4900px on the longest edge
51170px on the longest edge
61080px high
20300px high
21600px high
30256px on the longest edge
31450px high
10801080px on the longest edge
16001600px on the longest edge
20482048px on the longest edge
***

Categories

Categories of photos may be specified by their ID or string name, depending on the API method.

ID Category
0Uncategorized
10Abstract
29Aerial New!
11Animals
5Black and White
1Celebrities
9City and Architecture
15Commercial
16Concert
20Family
14Fashion
2Film
24Fine Art
23Food
3Journalism
8Landscapes
12Macro
18Nature
30Night New!
4Nude
7People
19Performing Arts
17Sport
6Still Life
21Street
26Transportation New!
13Travel
22Underwater
27Urban Exploration New!
25Wedding New!

License Types

500px currently supports these types of licenses, more details can be found at http://500px.com/creativecommons

ID License Type
0Standard 500px License
1Creative Commons License Non Commercial Attribution
2Creative Commons License Non Commercial No Derivatives
3Creative Commons License Non Commercial Share Alike
4Creative Commons License Attribution
5Creative Commons License No Derivatives
6Creative Commons License Share Alike
7Creative Commons License Public Domain Mark 1.0
8Creative Commons License Public Domain Dedication

Gallery kinds

* 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
  • categoryCategory 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

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
  • categoryCategory 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: 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"
}
You can’t perform that action at this time.