GET photos](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos.md)**
46 | - **[GET photos/search](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_search.md)**
47 | - **[GET photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id.md)**
48 | - **[GET photos/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_comments.md)**
49 | - **[GET photos/:id/votes](https://github.com/500px/api-documentation/blob/master/endpoints/photo/GET_photos_id_votes.md)**
50 | - **[PUT photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/PUT_photos_id.md)**
51 | - **[POST photos](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md)**
52 | - **[POST photos/:id/vote](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_vote.md)**
53 | - **[DELETE photos/:id/vote](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id_vote.md)**
54 | - **[POST photos/:id/tags](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_tags.md)**
55 | - **[POST photos/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_comments.md)**
56 | - **[POST photos/:id/report](https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos_id_report.md)**
57 | - **[DELETE photos/:id](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id.md)**
58 | - **[DELETE photos/:id/tags](https://github.com/500px/api-documentation/blob/master/endpoints/photo/DELETE_photos_id_tags.md)**
59 |
60 | #### User Resources
61 |
62 | - **[GET users](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users.md)**
63 | - **[GET users/show](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_show.md)**
64 | - **[GET users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_friends.md)**
65 | - **[GET users/:id/followers](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_id_followers.md)**
66 | - **[GET users/search](https://github.com/500px/api-documentation/blob/master/endpoints/user/GET_users_search.md)**
67 | - **[POST users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/POST_users_id_friends.md)**
68 | - **[DELETE users/:id/friends](https://github.com/500px/api-documentation/blob/master/endpoints/user/DELETE_users_id_friends.md)**
69 |
70 | #### Gallery Resources
71 |
72 | - **[GET users/:user_id/galleries](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries.md)**
73 | - **[GET users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md)**
74 | - **[GET users/:user_id/galleries/:id/items](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id_items.md)**
75 | - **[GET users/:user_id/galleries/:id/share_url](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md)**
76 | - **[PUT users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id.md)**
77 | - **[PUT users/:user_id/galleries/:id/items](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id_items.md)**
78 | - **[PUT users/:user_id/galleries/reposition](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_reposition.md)**
79 | - **[POST users/:user_id/galleries](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/POST_galleries.md)**
80 | - **[DELETE users/:user_id/galleries/:id](https://github.com/500px/api-documentation/blob/master/endpoints/galleries/DELETE_galleries_id.md)**
81 |
82 | #### Collections/Sets Resources
83 |
84 | - **DEPRECATED**. Please use [Gallery Resources](#gallery-resources) instead
85 |
86 | #### Comment Resources
87 |
88 | - **[POST comments/:id/comments](https://github.com/500px/api-documentation/blob/master/endpoints/comments/POST_comments_id_comments.md)**
89 |
90 | ## Directory API
91 |
92 | 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.
93 |
94 | ## Authentication
95 |
96 | - **[POST oauth/request_token](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md)**
97 | - **[POST oauth/authorize](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_authorize.md)**
98 | - **[POST oauth/access_token](https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_accesstoken.md)**
99 | - **[Upload key](https://github.com/500px/api-documentation/blob/master/authentication/upload_key.md)**
100 |
101 | ## FAQ
102 | ### What do I need to know before I start using the API?
103 | Got rust on your skills? No worries. Here are the docs you might need to get started:
104 |
105 | - HTTPS protocol
106 | - [REST software pattern][]
107 | - Authentication with [OAuth][] (or the official [Beginner’s Guide][])
108 | - Data serialization with [JSON][] (or see a [quick tutorial][])
109 |
110 | ### How do I connect to the 500px.com API?
111 | 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.
112 |
113 | ### What return formats do you support?
114 | 500px API currently returns data in [JSON](http://json.org/ "JSON") format.
115 |
116 | ### What kind of authentication is required?
117 | Applications must identify themselves to access any resource.
118 | 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.
119 |
120 | ### Is there a request rate limit?
121 | 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.
122 |
123 | [REST software pattern]: http://en.wikipedia.org/wiki/Representational_State_Transfer
124 | [OAuth]: http://oauth.net/core/1.0a/
125 | [Beginner’s Guide]: http://hueniverse.com/oauth/
126 | [JSON]: http://json.org
127 | [quick tutorial]: http://www.webmonkey.com/2010/02/get_started_with_json/
128 | [Register your application]: http://500px.com/settings/applications
129 | [API Terms of Use]: https://github.com/500px/api-documentation/blob/master/basics/terms_of_use.md
130 | [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
131 |
--------------------------------------------------------------------------------
/authentication/POST_oauth_accesstoken.md:
--------------------------------------------------------------------------------
1 | # OAuth
2 |
3 | POST oauth/access_token
4 |
5 | ## Description
6 | 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][].
7 |
8 | The OAuth Access Token may also be used for xAuth operations.
9 |
10 | ***
11 |
12 | ## Requires authentication
13 | 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.
14 |
15 | Note that this request must be signed with a Request Token even when using the xAuth workflow.
16 |
17 | ***
18 |
19 | ## Parameters
20 | Standard oAuth workflow:
21 |
22 | - **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request.
23 |
24 | xAuth workflow:
25 |
26 | - **x_auth_mode** _(required)_ — xAuth modificator. Recognized values: 'client_auth'.
27 | - **x_auth_username** _(required)_ — The username or email address of the user to obtain a token for.
28 | - **x_auth_password** _(required)_ — The password of the user for which to obtain a token for.
29 |
30 | ***
31 |
32 | ## Return format
33 | Text, containing an query string-encoded list of OAuth parameters.
34 |
35 | - **oauth_token** — An Access Token
36 | - **oauth_token_secret** — An Access Token's Secret
37 |
38 | ***
39 |
40 | ## Errors
41 |
42 | - **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
43 |
44 | [Section 6.3]: http://oauth.net/core/1.0/#auth_step3
45 | [OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
46 | [request_token]: https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md
47 |
--------------------------------------------------------------------------------
/authentication/POST_oauth_authorize.md:
--------------------------------------------------------------------------------
1 | # OAuth
2 |
3 | POST oauth/authorize
4 |
5 | ## Description
6 | 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.
7 |
8 | ***
9 |
10 | ## Requires authentication
11 | OAuth Request Token received using [request_token][] method.
12 |
13 | ***
14 |
15 | ## Parameters
16 |
17 | 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.
18 |
19 | - **oauth_token** _(required)_ — A Request Token received from [request_token][] method
20 | - **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request
21 |
22 | ***
23 |
24 | ## Return format
25 | The user will be redirected to oauth_callback URL once they authorize the request. The request will contain two parameters:
26 |
27 | - **oauth_token** — A Request Token issued by the Provider at the [request_token][] step
28 | - **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.
29 |
30 | ***
31 |
32 | ## Errors
33 |
34 | - **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
35 |
36 | [Section 6.2]: http://oauth.net/core/1.0/#auth_step2
37 | [OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
38 | [request_token]: https://github.com/500px/api-documentation/blob/master/authentication/POST_oauth_requesttoken.md
39 |
--------------------------------------------------------------------------------
/authentication/POST_oauth_requesttoken.md:
--------------------------------------------------------------------------------
1 | # OAuth
2 |
3 | POST oauth/request_token
4 |
5 | ## Description
6 | 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][].
7 |
8 | ***
9 |
10 | ## Requires authentication
11 | False
12 |
13 | ***
14 |
15 | ## Parameters
16 |
17 | 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.
18 |
19 | - **oauth_callback** _(required)_ — A valid URL on the Consumer side the user should be redirected to once they authorize the request.
20 |
21 | ***
22 |
23 | ## Return format
24 | Text, containing an query string-encoded list of OAuth parameters.
25 |
26 | - **oauth_token** — A Request Token
27 | - **oauth_token_secret** — A Request Token's Secret
28 |
29 | ***
30 |
31 | ## Errors
32 |
33 | - **401 Invalid OAuth Request** — Request for the token was malformed or uses an unknown OAuth version
34 |
35 | [Section 6.1]: http://oauth.net/core/1.0/#auth_step1
36 | [OAuth 1.0 authentication flow]: http://oauth.net/core/1.0/#anchor9
37 |
--------------------------------------------------------------------------------
/authentication/upload_key.md:
--------------------------------------------------------------------------------
1 | # Upload key authorization
2 |
3 | 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.
4 |
5 | ***
6 |
7 | ## Authentication requirements
8 | 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.
9 |
10 | ## Parameters
11 | To have an upload request authenticate successfully, the following parameters must be included:
12 |
13 | ## Return format
14 | Text, containing an query string-encoded list of OAuth parameters.
15 |
16 | - **consumer_key** — OAuth Consumer key of the application sending the request
17 | - **access_key** — An authorized OAuth Access Token received during the standard OAuth workflow
18 | - **upload_key** — Upload key received in the response to a [POST photos][] request
19 | - **photo_id** — The ID of the photo the file is being uploaded for
20 |
21 | [POST photos]: https://github.com/500px/api-documentation/blob/master/endpoints/photo/POST_photos.md
--------------------------------------------------------------------------------
/basics/formats_and_terms.md:
--------------------------------------------------------------------------------
1 | # Formats and Terms
2 |
3 | [500px.com][] allows discovery of the photography uploaded by users in a
4 | number of ways. An essential part of presentation is photo streams.
5 | Accessing the following streams is possible though means of the API:
6 |
7 | [500px.com]: http://500px.com/
8 |
9 | ***
10 |
11 | ## 500px Photo Terms
12 |
13 | ### Rating-based streams
14 | - [Popular][], photos with a rating over 80, sorted by rating, cached for 5 minutes
15 | - [Upcoming][], photos with a rating over 70, sorted by creation timestamp, cached for 5 minutes
16 |
17 | ### Time-based (Fresh) streams:
18 | - [Today][], photos created since midnight (EST time), cached for 60 seconds
19 | - [Yesterday][], photos created between last day’s midnight and past midnight (EST time), cached until the end of hour
20 | - [Week][], photos created in the past 7 days, excluding today, cached until the end of hour
21 |
22 | ### User-based streams:
23 | - [User’s Photos][], all active public photos of a given user
24 | - [User’s Friends’ Photos][Week], a collection of User’s Photos streams from all followings of a given user
25 |
26 | ### Special streams:
27 | - [Editors’ Choice][], photos selected by 500px.com Editors, cached indefinitely
28 |
29 | [Popular]: http://500px.com/popular
30 | [Upcoming]: http://500px.com/upcoming
31 | [Today]: http://500px.com/fresh/today
32 | [Yesterday]: http://500px.com/fresh/yesterday
33 | [Week]: http://500px.com/fresh/week
34 | [User’s Photos]: http://500px.com/iansobolev
35 | [Editors’ Choice]: http://500px.com/editors
36 |
37 | ***
38 |
39 | ## Image URLs and Image Sizes
40 |
41 | 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
42 |
43 | **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.
44 |
45 | 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:
46 |
47 | ```
48 | GET /v1/photos?feature=popular&image_size=3
49 | ```
50 |
51 | If you want to request multiple sizes, you can pass an array for `image_size` as well:
52 | ```
53 | GET /v1/photos?feature=popular&image_size[]=3&image_size[]=2
54 | ```
55 | which can equivalently be specified as:
56 | ```
57 | GET /v1/photos?feature=popular&image_size=3,2
58 | ```
59 |
60 | These are the standard cropped sizes:
61 | | ID | 64 |Dimensions | 65 |
|---|---|
| 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 |
| ID | 79 |Dimensions | 80 |
|---|---|
| 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 |
| ID | 100 |Category | 101 |
|---|---|
| 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! |
| ID | 140 |License Type | 141 |
|---|---|
| 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 | 158 |Gallery Kinds | 159 |Contents | 160 |
|---|---|---|
| 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. |
en, ru, de, ja, br, es.
297 | - **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.
298 | - **upgrade\_type** - Whether this is a paid user or trial user. Values: 0 - free user, 1 - trial user, 2 - paid user
299 | - **show\_nude** — Whether the user has content filter disabled, boolean.
300 | - **userpic\_url** — Profile picture’s URL of the user, string
301 | - **store\_on** - Whether the user has the store option enabled, boolean
302 | - **contacts** — A dictionary of user’s contacts, object. Keys should be treated as provider names, and values as user IDs with given provider.
303 | - **equipment** - A dictionary of a user's equipment. Possible keys are camera, lens, misc. Each key will have an array of values.
304 | - **photos\_count** — Number of active photos posted by the user, integer.
305 | - **galleries\_count** — Number of galleries visible on the user's profile, integer.
306 | - **affection** — Affection value, integer.
307 | - **friends\_count** — Number of people this user follows, integer.
308 | - **followers\_count** — Number of people this user is being followed by, integer.
309 | - **admin** - Boolean value that will be 1 if the user is a 500px team member.
310 | - **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.
311 |
312 | If the user you are requesting is the currently authenticated user these additional fields will be returned:
313 | - **email** - The user's email address.
314 | - **upload\_limit** - The remaining upload limit this user has, integer
315 | - **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
316 | - **upgrade\_expiry\_date** - The date at which the user's subscription will expire, timestamp
317 | - **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.
318 |
319 | If you are authenticated these additional fields will be returned:
320 | - **following** - A boolean value indicating whether or not you are following this user.
321 |
322 | ***
323 |
324 | ## Comment object formats
325 | The profile format of a User object includes the following data:
326 |
327 | ### Full format
328 | The full format of a Comment object includes the following data:
329 |
330 | - **id** — ID of the comment, integer
331 | - **body** — Content of the comment, string
332 | - **to_whom_user_id** — To which user the comment was made, string
333 | - **user_id** — User ID of author of the comment, string
334 | - **created_at** — Timestamp indicating time the comment was created, timestamp
335 | - **user** — Author's profile in [short format][], object
336 | - **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
337 | - **flagged** - A boolean value indicating whether or not this comment was flagged for review.
338 | - **rating** - The sum of the number of votes this comment has received, integer
339 |
340 | If you are authenticated these additional attributes will be returned:
341 |
342 | - **voted** - A boolean value indicating whether or not the currently authenticated user has voted on this comment.
343 |
344 | ***
345 |
346 | ## Gallery object formats
347 |
348 | ### Short format
349 | The short format of a Gallery object includes the following data:
350 |
351 | - **id** — ID of the gallery, integer
352 | - **user_id** — ID of the user that owns the gallery, integer
353 | - **name** — Title of the gallery, string
354 | - **description** — Description of the gallery, string
355 | - **subtitle** — A short (500 char.) blurb of the gallery, string
356 | - **items_count** — Number of items in the gallery, integer
357 | - **privacy** - Boolean value whether or not the gallery is private. A value of true means the gallery is private to the user
358 | - **kind** - Indicates the **[gallery kind][]**, integer
359 | - **created\_at** — Timestamp indicating time the gallery was created, timestamp
360 | - **updated\_at** — Timestamp indicating time the gallery was updated, timestamp
361 | - **cover_photo** - Array containing a JSON hash of the cover photo's id, size, url, and nsfw flag
362 | - **custom_path** - Custom path of the gallery, string
363 | - **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)**
364 | - **user** _(optional)_ - User who owns the gallery, in **[short format][]**
365 |
366 | ### Full format
367 |
368 | The full format of a Gallery object includes the following data:
369 |
370 | - **id** — ID of the gallery, integer
371 | - **user_id** — ID of the user that owns the gallery, integer
372 | - **name** — Title of the gallery, string
373 | - **description** — Description of the gallery, string
374 | - **cover_photo** - Array containing a JSON hash of the cover photo's id, size, url, and nsfw flag
375 | - **subtitle** — A short (500 char.) blurb of the gallery, string
376 | - **items_count** — Number of items in the gallery, integer
377 | - **privacy** - Boolean value whether or not the gallery is private. A value of true means the gallery is private to the user
378 | - **kind** - Indicates the **[gallery kind][]**, integer
379 | - **created\_at** — Timestamp indicating time the gallery was created, timestamp
380 | - **updated\_at** — Timestamp indicating time the gallery was updated, timestamp
381 | - **custom_path** - A slug for the gallery url, string
382 | - **editors_choice** - Boolean value indicating whether the gallery has been featured in editor's choice
383 | - **feature** - Name of stream where gallery has been featured. Values can be either 'popular' or 'fresh'
384 | - **featured_at** - Timestamp indicating when gallery was featured
385 | - **token** - Token signature for a private gallery url. Only returned if request is made by the gallery owner
386 | - **user** _(optional)_ - User who owns the gallery, in **[short format][]**
387 |
388 | ***
389 |
390 | ## Equipment object formats
391 |
392 | ### Camera info
393 |
394 | - **id** - ID of the camera, integer
395 | - **friendly_name** - Displayable name, eg. "Canon EOS 70D"
396 | - **name** - Actual name of the camera, eg. "EOS 70D"
397 | - **verified** - Whether or not this entry is verified, true or false
398 | - **features** - Short list of features, HTML-formatted string
399 | - **slug** - The slug, eg "eos-70d",
400 | - **camera_type** - The type of camera this is, one of
401 | - dslr
402 | - film
403 | - smartphone
404 | - mirrorless
405 | - compact
406 | - medium_format
407 | - film_scanner
408 | - action_camera
409 | - drone
410 | - **brand** - A small object containing brand info, eg.
411 | ```
412 | {
413 | "id": 1,
414 | "name": "Canon",
415 | "slug": "canon"
416 | }
417 | ```
418 |
419 | ### Lens info
420 |
421 | - **id** - ID of the lens, integer
422 | - **friendly_name** - Displayable name, eg. "Canon EF-S 10-18mm f/4.5-5.6 IS STM"
423 | - **name** - Actual name of the lens, eg. "EF-S 10-18mm f/4.5-5.6 IS STM"
424 | - **slug** - The slug, eg. "ef-s-10-18mm-f-4-5-5-6-is-stm"
425 | - **features** - Short list of features, HTML-formatted string
426 | - **brand** - A small object containing brand info, eg.
427 | ```
428 | {
429 | "id": 1,
430 | "name": "Canon",
431 | "slug": "canon"
432 | }
433 | ```
434 |
435 | [Category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
436 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
437 | [gallery kind]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#gallery-kinds
438 | [License type]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#license_types
439 |
--------------------------------------------------------------------------------
/basics/terms_of_use.md:
--------------------------------------------------------------------------------
1 | # Terms of Use
2 |
3 | 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).
4 |
5 | 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.
6 |
7 | ## Purpose
8 | 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.
9 |
10 | ## Registration
11 | 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.
12 |
13 | 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.
14 |
15 | ## Grant of 500px API License
16 | 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.
17 |
18 | 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.
19 |
20 | ## 500px API License Conditions and Restrictions
21 |
22 | ### You shall at all times:
23 | - **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"**
24 | - 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).
25 | - 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.
26 | - Remove from your application within 24 hours any 500px member’s photos, images or other information that the owner asks you to remove.
27 | - 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.
28 | - Provide 500px reasonable access to usage analytics of the application.
29 |
30 | ### You shall not:
31 | - Use 500px APIs for any application or purpose other than as approved by 500px.
32 | - 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.
33 | - Attempt to cloak or conceal your identity or your application’s identity when requesting authorization to use 500px APIs.
34 | - Display more than 20 500px photos or images per page in your application or use an unreasonable amount of bandwidth.
35 | - Cache or store any photos or images obtained from 500px for more than 24 hours.
36 | - Enable downloads or storage of photos that are protected by copyright by any application.
37 | - Use 500px as a generic image hosting service for banner advertisements, graphics, etc.
38 | - 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.
39 | - 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.
40 |
41 | #### Without limiting the generality of the foregoing, Use 500px APIs, post, email, transmit, upload or otherwise submit any content to 500px members that:
42 | - 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;
43 | could be harmful to minors;
44 | - harasses or advocates harassment of another person;
45 | - involves the transmission of "junk mail", "chain letters", or unsolicited mass mailing or "spamming";
46 | - promotes information that is false, misleading, illegal or promotes illegal activities or conduct that is abusive, threatening, obscene, defamatory or libelous;
47 | - 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;
48 | - 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;
49 | - contains restricted or password only access pages, or hidden pages or images (those not linked to or from another accessible page);
50 | - displays pornography or pornographic material of any kind;
51 | - 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;
52 | - provides instructional information about illegal activities such as making or buying illegal weapons, violating someone's privacy, or providing or creating computer viruses;
53 | - solicits 500px passwords or personal identifying information for unlawful purposes from 500px members;
54 | - engages in contests, sweepstakes, barter, advertising, and pyramid schemes, without our prior written consent;
55 | - promotes or is used in connection with spyware, adware, other malicious programs or code; and
56 | - 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.
57 |
58 |
59 | ## Termination
60 | 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.
61 |
62 | 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.
63 |
64 | ## Trademark License
65 | "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.
66 |
67 | 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."
68 | 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."
69 | You shall not use "500px" in your product name, domain name, or images.
70 | 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.
71 |
72 | ## Ownership
73 | 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.
74 |
75 | ## Support
76 | 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.
77 |
78 | ## Fees and Payments
79 | 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.
80 |
81 | ## Disclaimer of Warranty
82 | 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.
83 |
84 | 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.
85 |
86 | 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.
87 |
88 | ## Limitation of Liability
89 | 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.
90 |
91 | 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.
92 |
93 | 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.
94 |
95 | ## Release and Waiver of Liability
96 | 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.
97 |
98 | ## Indemnification
99 | 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.
100 |
101 | ## Arbitration
102 | 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.
103 |
104 | ## General Terms
105 | 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.
106 |
107 | 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.
108 |
109 | Published on August 16, 2011. Modified on May 29, 2012.
110 |
--------------------------------------------------------------------------------
/basics/upload.md:
--------------------------------------------------------------------------------
1 | # Uploading a photo
2 | To upload a photo, you need to do 2 requests:
3 | 1. `POST /photos`
4 | 1. `POST url-obtained-from-first-request`
5 |
6 | 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.
7 |
8 | 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)
9 | ``` json
10 | "presigned_post": {
11 | "url": "https://s3.amazonaws.com/photos.500px.net",
12 | "fields": {
13 | ...
14 | }
15 | }
16 | ```
17 |
18 | 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.
19 |
20 | Here's an example request, the fields are `form-data`:
21 | ```
22 | POST https://s3.amazonaws.com/photos.500px.net
23 |
24 | name="key" 238921583/cb47e80843a0eaaaaac2fc242c9cd6bcecd6f36/0.jpg
25 | name="x-amz-meta-user_id" 16972409
26 | name="x-amz-meta-client_application_id" 0
27 | name="x-amz-meta-user_agent" Chrome/62.0.3202.94 Safari/537.36
28 | name="x-amz-meta-user_ip" 206.223.171.146
29 | name="policy" eyJleHBpcmF0aW9uIjoiMjAxN...
30 | name="x-amz-credential" ASDASDASDASDASD/20171212/us-east-1/s3/aws1_request
31 | name="x-amz-algorithm" AWS4-HMAC-SHA256
32 | name="x-amz-date" 20171212T195326Z
33 | name="x-amz-signature" 47aa1...
34 | name="file"; filename="IMG_20171028_175620-01.jpeg"
35 | Content-Type: image/jpeg
36 |
37 | ...the file contents...
38 | ```
39 |
40 | ***
41 |
42 | ## Return format
43 | `POST /photos` will return HTTP status 200 on success. Proceed with the second request only when you get back the 200 status.
44 |
45 | `POST url-from-first-request` will return HTTP status 204 upon successful upload.
46 |
--------------------------------------------------------------------------------
/endpoints/collections/DELETE_collections_id.md:
--------------------------------------------------------------------------------
1 | ### DEPRECATED
2 |
3 | Please use the corresponding **[galleries endpoint][]**
4 |
5 | ***
6 |
7 | # Collections Resources
8 |
9 | DELETE collections/:collection_id
10 |
11 | ## Description
12 | Deletes collection.
13 |
14 | ***
15 |
16 | ## Requires authentication
17 | **[OAuth][]**
18 |
19 | ***
20 |
21 | ## Return format
22 | **TODO**
23 |
24 | ***
25 |
26 | ## Errors
27 | None
28 |
29 | ***
30 |
31 | ## Example
32 | **Request**
33 |
34 | GET v1/collections
35 |
36 | **Return**
37 |
38 | **TODO**
39 |
40 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
41 | [Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
42 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
43 | [galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/DELETE_galleries_id.md
44 |
--------------------------------------------------------------------------------
/endpoints/collections/GET_collections.md:
--------------------------------------------------------------------------------
1 | ### DEPRECATED
2 |
3 | Please use the corresponding **[galleries endpoint][]**
4 |
5 | ***
6 |
7 | # Collections Resources
8 |
9 | GET collections
10 |
11 | ## Description
12 | Returns a listing of all User's collections and sets.
13 |
14 | ***
15 |
16 | ## Requires authentication
17 | **[OAuth][]**
18 |
19 | ***
20 |
21 | ## Parameters
22 |
23 | - **photos_per_collection_limit** — The number of photos included in each collection. Can not be over 200, default 200.
24 |
25 | ***
26 |
27 | ## Return format
28 | A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
29 |
30 | ***
31 |
32 | ## Errors
33 | None
34 |
35 | ***
36 |
37 | ## Example
38 | **Request**
39 |
40 | GET v1/collections
41 |
42 | **Return**
43 | ``` json
44 | {
45 | "collections": [
46 | {
47 | "id": 289621,
48 | "title": "Film set",
49 | "position": 0,
50 | "created_at": "2012-05-24T10:13:34-04:00",
51 | "path": "film_set",
52 | "photos": [
53 | {
54 | "id": 7905188,
55 | "name": "St Lawrence Market Toronto",
56 | "rating": 0,
57 | "created_at": "2012-05-24T11:22:46-04:00",
58 | "category": 3,
59 | "image_url": "http://pcdn.500px.net/7905188/9e1fcf034f7492c92d0f98e504d80c0b80e15990/4.jpg",
60 | "votes_count": 0,
61 | "position": 1
62 | },
63 | {
64 | "id": 7905189,
65 | "name": "Distillery district Toronto",
66 | "rating": 0,
67 | "created_at": "2012-05-24T11:22:49-04:00",
68 | "category": 3,
69 | "image_url": "http://pcdn.500px.net/7905189/cc0ff39d30614fea56f2583ec796460d6a05d69c/4.jpg",
70 | "votes_count": 0,
71 | "position": 2
72 | }
73 | ]
74 | },
75 | {
76 | "id": 298603,
77 | "title": "Bikes set",
78 | "position": 1,
79 | "created_at": "2012-06-07T13:15:26-04:00",
80 | "path": "bikes_set",
81 | "photos": [
82 | {
83 | "id": 7651996,
84 | "name": "bike",
85 | "rating": 48.7,
86 | "created_at": "2012-05-16T11:47:12-04:00",
87 | "category": 26,
88 | "image_url": "http://pcdn.500px.net/7651996/bfc9a0ae7cfaed28ebc947c2d4cd79e60a04934d/4.jpg",
89 | "votes_count": 2,
90 | "position": 1
91 | }
92 | ]
93 | }
94 | ]
95 | }
96 | ```
97 |
98 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
99 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
100 | [galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries.md
101 |
--------------------------------------------------------------------------------
/endpoints/collections/GET_collections_id.md:
--------------------------------------------------------------------------------
1 | ### DEPRECATED
2 |
3 | Please use the corresponding **[galleries endpoint][]**
4 |
5 | ***
6 |
7 | # Collections Resources
8 |
9 | GET collections/:id
10 |
11 | ## Description
12 | Returns a collection.
13 |
14 | ***
15 |
16 | ## Requires authentication
17 | **[OAuth][]**
18 |
19 | ***
20 |
21 | ## Parameters
22 |
23 | - **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```.
24 |
25 | ***
26 |
27 | ## Return format
28 | A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
29 |
30 | ***
31 |
32 | ## Errors
33 | None
34 |
35 | ***
36 |
37 | ## Example
38 | **Request**
39 |
40 | GET v1/collections/52&image_size=3
41 |
42 | **Return**
43 | ``` json
44 | {
45 | "id": 52,
46 | "title": "models",
47 | "position": 0,
48 | "created_at": "2012-06-04T13:55:08-04:00",
49 | "path": "models",
50 | "kind": "portfolio",
51 | "photos": [
52 | {
53 | "id": 500,
54 | "name": "Maria | portrait 1",
55 | "rating": 0,
56 | "created_at": "2012-06-04T10:18:18-04:00",
57 | "category": 0,
58 | "image_url": "http://dpcdn.500px.net/500/1e38495dab54fbe8bcc3b7a3679ee8f52e34cc8f/4.jpg",
59 | "images":[
60 | {"size":3,
61 | "url":"http://dpcdn.500px.org/500/9661dc2247a00f115456a3af08b804cb61d493cd/3.jpg?v=0",
62 | "https_url":"https://gp1.wac.edgecastcdn.net/806614/photos/photos.500px.net/500/9661dc2247a00f115456a3af08b804cb61d493cd/3.jpg?v=0"}],
63 | "votes_count": 0,
64 | "position": 999
65 | },
66 | {
67 | "id": 499,
68 | "name": "Maria | portrait 2",
69 | "rating": 0,
70 | "created_at": "2012-06-04T10:18:12-04:00",
71 | "category": 0,
72 | "image_url": "http://dpcdn.500px.net/499/3a323000e7b9ca7676b01de3916543c479e636f0/4.jpg",
73 | "images":[
74 | {"size":3,
75 | "url":"http://ppcdn.500px.org/499/573b00d542f811de627c4cbb0fb1c1c09b76e729/3.jpg?v=0",
76 | "https_url":"https://gp1.wac.edgecastcdn.net/806614/photos/photos.500px.net/499/573b00d542f811de627c4cbb0fb1c1c09b76e729/3.jpg?v=0"}]
77 | "votes_count": 0,
78 | "position": 999
79 | }
80 | ]
81 | }
82 | ```
83 |
84 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
85 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
86 | [galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/GET_galleries_id.md
87 |
--------------------------------------------------------------------------------
/endpoints/collections/POST_collections.md:
--------------------------------------------------------------------------------
1 | ### DEPRECATED
2 |
3 | Please use the corresponding **[galleries endpoint][]**
4 |
5 | ***
6 |
7 | # Collections Resources
8 |
9 | POST collections
10 |
11 | ## Description
12 | Creates new a collection.
13 |
14 | ***
15 |
16 | ## Requires authentication
17 | **[OAuth][]**
18 |
19 | ## Parameters
20 |
21 | Essential information:
22 |
23 | - **title** _(required)_ — Title for the collection.
24 | - **path** _(required)_ — Path where the collection will be accessible at 500px.com/user/sets/:path.
25 | - **kind** — Kind of the Collection to be created Recognized values: 1 - Portfolio Set (default), 2 - Profile Set.
26 | - **photo_ids** — Comma separated list of Photo ID values to post with the blog.
27 |
28 | Optional information:
29 |
30 | - **position** — Position of the collection in the list of collections.
31 |
32 | ***
33 |
34 | ## Return format
35 | A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
36 |
37 | ***
38 |
39 | ## Errors
40 |
41 | - **path** — path of the collection has already been taken.
42 | - **403 Forbidden** — You have to upgrade to create portfolios and sets.
43 |
44 | ***
45 |
46 | ## Example
47 | **Request**
48 |
49 | POST v1/collections?title=bikes&path=bikes
50 |
51 | **Return**
52 | ``` json
53 | {
54 | "id": 298782,
55 | "title": "bikes",
56 | "position": 10,
57 | "created_at": "2012-06-07T17:36:17-04:00",
58 | "path": "bikes",
59 | "photos": []
60 | }
61 | ```
62 |
63 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
64 | [Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
65 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
66 | [galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/POST_galleries.md
67 |
--------------------------------------------------------------------------------
/endpoints/collections/PUT_collections_id.md:
--------------------------------------------------------------------------------
1 | ### DEPRECATED
2 |
3 | Please use the corresponding **[galleries endpoint][]**
4 |
5 | ***
6 |
7 | # Collections Resources
8 |
9 | PUT collections/:id
10 |
11 | ## Description
12 | Updates collection.
13 |
14 | ***
15 |
16 | ## Requires authentication
17 | **[OAuth][]**
18 |
19 | ## Parameters
20 |
21 | Essential information:
22 |
23 | - **id** _(required)_ — Collection ID.
24 | - **title** — Title for the collection.
25 | - **path** — Path where the collection will be accessible at 500px.com/user/sets/:path.
26 | - **photo_ids** — Comma separated list of Photo ID values that are in this collection.
27 | - **kind** — Change kind of the Collection. Recognized values: 1 - Portfolio Set, 2 - Profile Set.
28 |
29 | Optional information:
30 |
31 | - **position** — Position of the collection in the list of collections.
32 |
33 | ***
34 |
35 | ## Return format
36 | A JSON object with **collections** — An indexed array of Collection objects in **[short format][]**.:
37 |
38 | ***
39 |
40 | ## Errors
41 | None
42 |
43 | ***
44 |
45 | ## Example
46 | **Request**
47 |
48 | PUT v1/collections/298603?title=Bikes&photo_ids=7651996
49 |
50 | **Return**
51 | ``` json
52 | {
53 | id: 298603,
54 | title: "Bikes",
55 | position: 0,
56 | created_at: "2012-06-07T13:15:26-04:00",
57 | path: "bikes_set",
58 | photos: [
59 | {
60 | id: 7651996,
61 | name: "bike",
62 | rating: 48.7,
63 | created_at: "2012-05-16T11:47:12-04:00",
64 | category: 26,
65 | image_url: "http://pcdn.500px.net/7651996/bfc9a0ae7cfaed28ebc947c2d4cd79e60a04934d/4.jpg",
66 | votes_count: 2,
67 | position: 999
68 | }
69 | ]
70 | }
71 | ```
72 |
73 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
74 | [Feature]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#500px-photo-terms
75 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-1
76 | [galleries endpoint]: https://github.com/500px/api-documentation/blob/master/endpoints/galleries/PUT_galleries_id.md
77 |
--------------------------------------------------------------------------------
/endpoints/comments/POST_comments_id_comments.md:
--------------------------------------------------------------------------------
1 | # Comment Resources
2 |
3 | POST comments/:id/comments
4 |
5 | ## Description
6 | 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.
7 |
8 | ***
9 |
10 | ## Requires authentication
11 | **[OAuth][]**
12 |
13 | ***
14 |
15 | ## Parameters
16 | - **body** _(required)_ — Content of the comment.
17 |
18 | ***
19 |
20 | ## Return format
21 | 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.
22 |
23 | ***
24 |
25 | ## Errors
26 | 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.
27 |
28 | - **400 Bad Request** — The body of the comment was not specified.
29 | - **404 Not Found** — The specified comment was not found.
30 |
31 | ***
32 |
33 | ## Example
34 | **Request**
35 |
36 | POST v1/comments/73249443/comments
37 |
38 | **Body**
39 |
40 | body=Nice+color+and+composition.
41 |
42 | **Result**
43 | ``` json
44 | {
45 | "status" : 200,
46 | "message" : "Successfully added a comment.",
47 | "error" : "None"
48 | "comment": {
49 | "id": 83858343,
50 | "user_id": 198867,
51 | "to_whom_user_id": 347823,
52 | "body": "Nice color and composition.",
53 | "created_at": "2013-02-25T17:35:26-05:00",
54 | "parent_id": 73249443,
55 | "flagged": false,
56 | "rating": 0,
57 | "voted": false,
58 | "user": {
59 | "id": 198867,
60 | "username": "tye",
61 | "firstname": "Tye",
62 | "lastname": "Shavik",
63 | "city": "Toronto",
64 | "country": "Canada",
65 | "fullname": "Tye Shavik",
66 | "userpic_url": "http://acdn.500px.net/198867/7f5f29fd33e093062a30e2bf3a9e605c446ba960/1.jpg?29",
67 | "upgrade_status": 2,
68 | "followers_count": 36,
69 | "affection": 103,
70 | "admin": 1
71 | }
72 | }
73 | }
74 | ```
75 |
76 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
--------------------------------------------------------------------------------
/endpoints/galleries/DELETE_galleries_id.md:
--------------------------------------------------------------------------------
1 | # Galleries Resources
2 |
3 | DELETE users/:user_id/galleries/:id
4 |
5 | ## Description
6 |
7 | Deletes the gallery.
8 |
9 | ***
10 |
11 | ## Requires authentication
12 | **[OAuth][]**
13 |
14 | ***
15 |
16 | ## Parameters
17 |
18 | - **id** _(required)_ — The ID of the gallery to delete.
19 |
20 | ***
21 |
22 | ## Return format
23 | A JSON object containing keys: **status**, **message** and **error** (if an error occurred).
24 |
25 | ***
26 |
27 | ## Errors
28 | 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.
29 |
30 | - **403 Forbidden** — You do not own the gallery you are trying to delete.
31 | - **404 Not Found** — The gallery you are trying to delete does not exist, or is private (and you are not its owner)
32 |
33 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
34 |
--------------------------------------------------------------------------------
/endpoints/galleries/GET_galleries.md:
--------------------------------------------------------------------------------
1 | # Galleries Resources
2 |
3 | GET users/:user_id/galleries
4 |
5 | ## Description
6 |
7 | Returns a listing of twenty (up to one hundred) galleries for the given user.
8 |
9 | ***
10 |
11 | ## Requires authentication
12 | * A valid Consumer Key must be provided in the **consumer_key** parameter.
13 | * Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
14 |
15 | ***
16 |
17 | ## Parameters
18 | - **sort** — Sort galleries in the specified order.
19 | ###### Recognized values:
20 | - 'created_at' — Sort by time of creation
21 | - 'updated_at' — Sort by time of last change (photo added or removed). This is the default.
22 | - 'last_added_to_at' — Sort by time last photo was added to the gallery.
23 | - 'rating' — Sort by gallery rating
24 | - 'position' — Sort by gallery position (as defined by the user)
25 |
26 | - **cover_size** — The cover photo size to be returned, if `include_cover` is set. Defaults to 4.
27 | - **include_cover** — If 1, the user's cover is included.
28 | - **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.
29 | ###### Recognized values:
30 | - 'asc' — Sort in ascending order (lowest or least-recent first). This is the default.
31 | - 'desc' — Sort in descending order (highest or most-recent first).
32 |
33 | - **privacy** — The privacy level of the galleries to return.
34 | ###### Recognized values:
35 | - 'private' — Only include the user's private galleries in the response. Only available for the current user.
36 | - 'public' — Only include the user's public galleries in the response. This is the default.
37 | - 'both' - Include both the public and private galleries in the response. Only available for the current user.
38 |
39 | - **kinds** — A comma-separated list of **[gallery kinds][]**. Default is to return all galleries.
40 | - **page** — Return a specific page in the photo stream. Page numbering is 1-based.
41 | - **rpp** — The number of results to return. Cannot be over 100, default 20.
42 |
43 | ***
44 |
45 | ## Return format
46 | A JSON object with the following keys and values:
47 |
48 | - **filters** — Additional filters that were used:
49 | - 'privacy' — The value of the privacy filter used;
50 | - 'kinds' — The value of the **[gallery kinds][]** requested;
51 | - **current_page** — Number of the page that is returned.
52 | - **total_pages** — Total number of pages in this feature's stream.
53 | - **total_items** — Total number of items in this feature's stream.
54 | - **galleries** — An array of Gallery objects in **[short format][]**.
55 |
56 | ***
57 |
58 | ## Errors
59 | - **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
60 |
61 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
62 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format-3
63 | [gallery kinds]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#gallery-kinds
64 |
--------------------------------------------------------------------------------
/endpoints/galleries/GET_galleries_id.md:
--------------------------------------------------------------------------------
1 | # Galleries Resources
2 |
3 | GET users/:user_id/galleries/:id
4 |
5 | ## Description
6 |
7 | Returns the details of the requested gallery
8 |
9 | `:id` can be one of the following:
10 |
11 | * gallery id
12 | * gallery path
13 | * gallery token
14 |
15 | Gallery id and path can be used to access any publicly-shared galleries, while
16 | knowing a gallery's secret token allows access to the corresponding private galler (regardless of ownership).
17 | The gallery id can be used to access any gallery owned by the current user (public or private).
18 |
19 | ***
20 |
21 | ## Requires authentication
22 | * A valid Consumer Key must be provided in **consumer_key** parameter.
23 | * Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
24 |
25 | ***
26 |
27 | ## Parameters
28 | - **cover_size** — The cover photo size to be returned. Defaults to 4.
29 |
30 | ***
31 |
32 | ## Return format
33 | The requested Gallery object in **[full format][]**.
34 |
35 | ***
36 |
37 | ## Errors
38 | 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.
39 |
40 | - **404 Not Found** — The gallery you are requesting does not exist, or is private (and you are not its owner)
41 |
42 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
43 | [full format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#full-format-3
44 |
--------------------------------------------------------------------------------
/endpoints/galleries/GET_galleries_id_items.md:
--------------------------------------------------------------------------------
1 | # Galleries Resources
2 |
3 | GET users/:user_id/galleries/:id/items
4 |
5 | ## Description
6 |
7 | Returns a listing of twenty (up to one hundred) photos in the given gallery.
8 |
9 | ***
10 |
11 | ## Requires authentication
12 | * A valid Consumer Key must be provided in **consumer_key** parameter.
13 | * Alternatively, a valid **[OAuth][]** request with an authorized Access Token will be accepted.
14 |
15 | ***
16 |
17 | ## Parameters
18 | - **only** — String name of the **[category][]** to return photos from. **Note:** Case sensitive, separate multiple values with a comma.
19 | - **exclude** — String name of the **[category][]** to exclude photos by. **Note:** Case sensitive, separate multiple values with a comma.
20 | - **sort** — Sort photos in the specified order.
21 | ###### Recognized values:
22 | - 'created_at' — Sort by time of upload.
23 | - 'rating' — Sort by rating.
24 | - 'highest_rating' — Sort by the highest rating the photo reached.
25 | - 'times_viewed' — Sort by view count.
26 | - 'votes_count' — Sort by number of likes.
27 | - 'comments_count' — Sort by number of comments.
28 | - 'taken_at' — Sort by the original date of the image extracted from metadata (might not be available for all images).
29 | - 'position' — Sort by the user's manually defined order. This is the default.
30 |
31 | - **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.
32 | ###### Recognized values:
33 | - 'asc' — Sort in ascending order (lowest or least-recent first). This is the default.
34 | - 'desc' — Sort in descending order (highest or most-recent first).
35 |
36 | - **page** — Return a specific page in the photo stream. Page numbering is 1-based.
37 | - **rpp** — The number of results to return. Cannot be over 100, default 20.
38 | - **image_size** — The photo size to be returned. It has to be an integer: 1 to 4. Also an array is accepted:
39 | ###### Example:
40 | - '&image_size=3'
41 | - '&image_size[]=3&image_size[]=4'
42 |
43 | - **include_store** — If set to 1, returns market infomation about the photo.
44 | ###### Returned values:
45 | - 'store_download' — Boolean value if the picture is avaliable for HD Download purchase.
46 | - 'store_print' — Boolean value if the picture is avaliable for Canvas print purchase.
47 | - 'store_license' — Boolean value if the picture is avaliable for Prime purchase.
48 | - 'store_width' — Integer value indicating the store size of the photo.
49 | - 'store_height' — Integer value indicating the store size of the photo.
50 |
51 | - **include_states** — If set to 1, returns state of the photo for the currently logged in user and authenticated request.
52 | ###### Returned values:
53 | - 'liked' — Boolean value whether the current user has liked this photo
54 | - 'purchased' — Boolean value whether the current user has bought this photo
55 |
56 | - **include_tags** (or **tags**) — If set to 1, returns an array of tags for the photo.
57 |
58 | - **include_missing** — If set to 1, returns ids of photos that have been deleted, made private or the owner of the photo is deactivated.
59 |
60 | - **include_geo** — If set to 1, returns location information about the photo.
61 |
62 | - **include_licensing** — If set to 1, returns licensing information for the photo.
63 |
64 | ***
65 |
66 | ## Return format
67 | A JSON object with the following keys and values:
68 |
69 | - **filters** — Additional filters that were used:
70 | - 'category' — The ID of the **[category][]** that photos were filtered by;
71 | - 'exclude' - The ID of the **[category][]** that photos were excluded;
72 | - **current_page** — Number of the page that is returned.
73 | - **total_pages** — Total number of pages in this feature's stream.
74 | - **total_items** — Total number of items in this feature's stream.
75 | - **photos** — An array of Photo objects in **[short format][]**.
76 |
77 | ***
78 |
79 | ## Errors
80 | 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.
81 |
82 | - **400 Bad Request** — The request issued is missing one or more of the required parameters or contains parameters in an invalid form.
83 | - **404 Not Found** — The gallery you are requesting does not exist, or is private (and you are not its owner)
84 |
85 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
86 | [category]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#categories
87 | [short format]: https://github.com/500px/api-documentation/blob/master/basics/formats_and_terms.md#short-format
88 |
--------------------------------------------------------------------------------
/endpoints/galleries/GET_galleries_id_share_url.md:
--------------------------------------------------------------------------------
1 | # Galleries Resources
2 |
3 | ```
4 | GET users/:user_id/galleries/:id/share_url
5 | ```
6 |
7 | # Description
8 |
9 | Returns a sharable private URL for the given gallery.
10 |
11 | # Requires authentication
12 | * Requires a valid **[OAuth][]** request with an authorized Access Token.
13 |
14 | [OAuth]: https://github.com/500px/api-documentation/tree/master/authentication
15 |
16 | # Parameters
17 |
18 | None
19 |
20 | # Return format
21 |
22 | ```json
23 | {
24 | "share_url" : "g/lib/TwitterOAuth.php make the following adjustments:
6 |
7 | $host = 'https://api.500px.com/v1/';
8 |
9 | And set up the URLs:
10 |
11 | /* Set API URLS */
12 | function accessTokenURL() { return 'https://api.500px.com/v1/oauth/access_token'; }
13 | function authenticateURL() { return 'https://api.500px.com/v1/oauth/authorize'; }
14 | function authorizeURL() { return 'https://api.500px.com/v1/oauth/authorize'; }
15 | function requestTokenURL() { return 'https://api.500px.com/v1/oauth/request_token'; }
16 |
17 | Change the example index.php from:
18 |
19 | /* If method is set change API call made. Test is called by default. */
20 | #$content = $connection->get('account/verify_credentials');
21 |
22 | To:
23 |
24 | /* Retrieve all photos in category Journalism that were uploaded today */
25 | $content = $connection->get('photos', array('feature' => 'fresh_today', 'only' => 'Journalism'));
26 |
27 | [oauth-php-wiki]: http://example.com/ "OAuth - Consumer and Server library for PHP"
28 | [@abraham's]: http://twitter.com/abraham "@abraham"
29 | [twitteroauth]: https://github.com/abraham/twitteroauth "TwitterOAuth"
30 |
--------------------------------------------------------------------------------
/examples/Ruby/xauth.rb:
--------------------------------------------------------------------------------
1 | require 'rubygems'
2 | require 'oauth'
3 | require 'multi_json'
4 |
5 | CONSUMER_KEY = ''
6 | CONSUMER_SECRET = ''
7 | USERNAME = ''
8 | PASSWORD = ''
9 |
10 | BASE_URL = 'https://api.500px.com'
11 |
12 | def get_access_token
13 | p "get_access_token: Initializing Consumer"
14 | consumer = OAuth::Consumer.new(CONSUMER_KEY, CONSUMER_SECRET, {
15 | :site => BASE_URL,
16 | :request_token_path => "/v1/oauth/request_token",
17 | :access_token_path => "/v1/oauth/access_token",
18 | :authorize_path => "/v1/oauth/authorize"})
19 |
20 | request_token = consumer.get_request_token()
21 | p "Request URL: #{request_token.authorize_url}"
22 | access_token = consumer.get_access_token(request_token, {}, { :x_auth_mode => 'client_auth', :x_auth_username => USERNAME, :x_auth_password => PASSWORD })
23 | access_token
24 | end
25 |
26 | access_token = get_access_token
27 | p "token: #{access_token.token}"
28 | p "secret: #{access_token.secret}"
29 |
30 |
31 | #p access_token.get('/v1/photos.json').body
32 | p MultiJson.decode(access_token.get('/v1/users.json').body).inspect
--------------------------------------------------------------------------------
/examples/iOS/API Tutorials.md:
--------------------------------------------------------------------------------
1 | # 500px API Tutorial
2 |
3 | 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?
4 |
5 | ## Specifics
6 |
7 | 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.
8 |
9 | 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.
10 |
11 | ## Signing Requests with your Consumer Key
12 |
13 | 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`.
14 |
15 | ## Signing Requests with OAuth
16 |
17 | Signing requests with OAuth is, unsurprisingly, more complicated. First off, you'll need to authenticate your user.
18 |
19 | ### Three-Legged OAuth Authentication
20 |
21 | 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.
22 |
23 | ### Two-Legged OAuth Authentication
24 |
25 | Two-legged OAuth authentication, sometimes referred to as XAuth, is also possible if we enabled it on your account. Just ask nicely :)
26 |
27 | 1. ### Obtain a request token.
28 |
29 | 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.
30 | > oauth_token=TOKEN_HERE&oauth_token_secret=SECRET_HERE&oauth_callback_confirmed=true
31 | Extract these out for the next step.
32 |
33 | 2. ### Obtain Access Token
34 |
35 | 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:
36 |
37 | NSArray * parameterArray = [NSArray arrayWithObjects:
38 | [NSString stringWithFormat:@"%@=%@", @"x_auth_mode", @"client_auth"],
39 | [NSString stringWithFormat:@"%@=%@", @"x_auth_password", [thePassword urlEncode]],
40 | [NSString stringWithFormat:@"%@=%@", @"x_auth_username", [theUserName urlEncode]], nil];
41 | [postRequest setHTTPBody:[[parameterArray componentsJoinedByString:@"&"] dataUsingEncoding:NSUTF8StringEncoding]];
42 |
43 | 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:
44 |
45 | NSArray * keysAndValues = [NSArray arrayWithObjects:
46 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_nonce", [self.nonce urlEncode]],
47 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature_method", [@"HMAC-SHA1" urlEncode]],
48 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_timestamp", [self.timestamp urlEncode]],
49 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_consumer_key", [kConsumerKey urlEncode]],
50 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_token", [theRequestToken urlEncode]],
51 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature", [SIGNATURE_HERE urlEncode]],
52 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_version", [[NSString stringWithString:@"1.0"] urlEncode]],
53 | nil];
54 |
55 | [postRequest addValue:[NSString stringWithFormat:@"OAuth %@", [keysAndValues componentsJoinedByString:@", "] forHTTPHeaderField:@"Authorization"];
56 |
57 | 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.
58 |
59 | 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:
60 |
61 | NSString * secret = [NSString stringWithFormat:@"%@&%@", YOUR_CONSUMER_KEY_HERE, theRequestSecret];
62 |
63 | NSData * secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
64 | NSData * baseData = [BASE_STRING_HERE dataUsingEncoding:NSUTF8StringEncoding];
65 |
66 | uint8_t digest[20] = {0};
67 | CCHmac(kCCHmacAlgSHA1, secretData.bytes, secretData.length,
68 | baseData.bytes, baseData.length, digest);
69 |
70 | NSData * signatureData = [NSData dataWithBytes:digest length:20];
71 | return [signatureData base64EncodedString];
72 |
73 | 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:
74 |
75 | NSString * url = [theURL urlEncode]; //this is the URL we're calling, should be https://api.500px.com/v1/oauth/access_token
76 |
77 | NSString * parameters;
78 |
79 | NSString * oauth_consumer_key = [YOUR_CONSUMER_KEY urlEncode];
80 | NSString * oauth_nonce = [self.nonce urlEncode];
81 | NSString * oauth_signature_method = [[NSString stringWithString:@"HMAC-SHA1"] urlEncode];
82 | NSString * oauth_timestamp = [self.timestamp urlEncode];
83 | NSString * oauth_version = [[NSString stringWithString:@"1.0"] urlEncode];
84 | NSString * x_auth_mode = [@"client_auth" urlEncode];
85 | NSString * x_auth_password = [[thePassword urlEncode] urlEncode]; //These are double-encoded on purpose
86 | NSString * x_auth_username = [[theUserName urlEncode] urlEncode];
87 |
88 | NSArray * params = [NSArray arrayWithObjects:
89 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_consumer_key", oauth_consumer_key],
90 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_nonce", oauth_nonce],
91 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_signature_method", oauth_signature_method],
92 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_timestamp", oauth_timestamp],
93 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_token", theRequestToken],
94 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_version", oauth_version],
95 | nil];
96 |
97 | params = [params arrayByAddingObjectsFromArray:[NSArray arrayWithObjects:[NSString stringWithFormat:@"%@%%3D%@", @"x_auth_mode", x_auth_mode],
98 | [NSString stringWithFormat:@"%@%%3D%@", @"x_auth_password", x_auth_password],
99 | [NSString stringWithFormat:@"%@%%3D%@", @"x_auth_username", x_auth_username], nil]];
100 | //sort paramaters lexicographically
101 | params = [params sortedArrayUsingSelector:@selector(compare:)];
102 |
103 | parameters = [params componentsJoinedByString:@"%26"];
104 |
105 | NSArray * baseComponents = [NSArray arrayWithObjects:
106 | theHTTPMethod,
107 | url,
108 | parameters,
109 | nil];
110 | NSString * baseString = [baseComponents componentsJoinedByString:@"&"];
111 |
112 | 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.
113 |
114 | ## Signing Requests
115 |
116 | 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:
117 |
118 | 
119 |
120 | The process to create this request is represented in the following flow chart.
121 |
122 | 
123 |
124 | 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).
125 |
126 | The value of the `Authorization` HTTP header field is:
127 |
128 | OAuth SORTED_KEY_VALUE_PAIRS_HERE.
129 |
130 | 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:
131 |
132 | NSArray * keysAndValues = [NSArray arrayWithObjects:
133 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_consumer_key", [kConsumerKey urlEncode]],
134 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_nonce", [self.nonce urlEncode]],
135 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature", [YOUR_SIGNATURE_HERE urlEncode]],
136 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_signature_method", [[NSString stringWithString:@"HMAC-SHA1"] urlEncode]],
137 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_timestamp", [self.timestamp urlEncode]],
138 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_token", [theToken urlEncode]],
139 |
140 | [NSString stringWithFormat:@"%@=\"%@\"", @"oauth_version", [[NSString stringWithString:@"1.0"] urlEncode]], nil];
141 |
142 | return [NSString stringWithFormat:@"OAuth %@", [keysAndValues componentsJoinedByString:@", "]];
143 |
144 | 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:
145 |
146 | NSString * secret = [NSString stringWithFormat:@"%@&%@", kConsumerSecret, theSecret];
147 |
148 | NSData * secretData = [secret dataUsingEncoding:NSUTF8StringEncoding];
149 | NSData * baseData = [YOUR_BASE_STRING_HERE dataUsingEncoding:NSUTF8StringEncoding];
150 |
151 | uint8_t digest[20] = {0};
152 | CCHmac(kCCHmacAlgSHA1, secretData.bytes, secretData.length,
153 | baseData.bytes, baseData.length, digest);
154 |
155 | NSData * signatureData = [NSData dataWithBytes:digest length:20];
156 | return [signatureData base64EncodedString];
157 |
158 | 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:
159 |
160 | NSString * url = [theURL urlEncode];
161 |
162 | NSString * parameters;
163 |
164 | NSString * oauth_consumer_key = [kConsumerKey urlEncode];
165 | NSString * oauth_nonce = [self.nonce urlEncode];
166 | NSString * oauth_signature_method = [[NSString stringWithString:@"HMAC-SHA1"] urlEncode];
167 | NSString * oauth_timestamp = [self.timestamp urlEncode];
168 | NSString * oauth_version = [[NSString stringWithString:@"1.0"] urlEncode];
169 |
170 | NSArray * params = [NSArray arrayWithObjects:
171 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_consumer_key", oauth_consumer_key],
172 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_nonce", oauth_nonce],
173 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_signature_method", oauth_signature_method],
174 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_timestamp", oauth_timestamp],
175 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_token", theToken],
176 | [NSString stringWithFormat:@"%@%%3D%@", @"oauth_version", oauth_version],
177 | nil];
178 | NSArray *keys = [theOptions allKeys];
179 | for (id key in keys)
180 | {
181 | params = [params arrayByAddingObject:[[NSString stringWithFormat:@"%@=%@", [key urlEncode], [[theOptions valueForKey:key] urlEncode]] urlEncode]];
182 | }
183 |
184 | //sort paramaters lexicographically
185 | params = [params sortedArrayUsingSelector:@selector(compare:)];
186 |
187 | parameters = [params componentsJoinedByString:@"%26"];
188 |
189 | NSArray * baseComponents = [NSArray arrayWithObjects:
190 | theHTTPMethod,
191 | url, //The URL you're requesting, *not* including any GET parameters
192 | parameters,
193 | nil];
194 | NSString * baseString = [baseComponents componentsJoinedByString:@"&"];
195 |
196 | ### POST
197 |
198 | 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.
199 |
200 | ### GET
201 |
202 | GET parameters are added to the end of URLs. They should not be URL-encoded, but *do* need to be lexicographically sorted.
203 |
204 | ### DELETE
205 |
206 | Whenever you want to DELETE an item, send a POST request instead with `_method` parameter set to "`delete`".
207 |
208 | ## Photo Streams
209 |
210 | 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.
211 |
212 | 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.
213 |
214 | Specifying specific users (`user` or `user_friends` features) requires either specifying a `user_id` or `username` parameter.
215 |
216 | 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.
217 |
218 | 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).
219 |
220 | Optionally, you may specify an `image_size` parameter to specify the size of the thumbnail contained in each short-form photo model.
221 |
222 | | image_size | Thumbnail Sizes |
|---|---|
| 1 | 70 x 70 |
| 2 | 140 x 140 |
| 3 | 280 x 280 |
| 4 | 900 wide or 900 tall, max |
| Contact Type | Dictionary Key |
|---|---|
| Google+ | googleplus |
| Personal Website | website |
| Personal Blog | blog |
| Flickr | flickr |
| Live Journal | livejournal |
| Skype | skype |
| Google Talk | googletalk |
| Tumblr | tumblr |