API

The Pongr API opens up raw Pongr data and functionality to your own applications. Using the standard RESTful, JSON-over-HTTP approach, your web, mobile or desktop apps can access, use and update Pongr data in almost any way you’d like.

The Pongr API is made up of many individual RESTful web services. Each web service method provides one type of data or functionality. Your app requests data from, or sends data to, the API over HTTP. In general, a GET request retrieves data from the API, a POST or PUT sends data to the API, and a DELETE, well, deletes data from the API. The API returns data in JSON format, and accepts data either in standard form-encoded or JSON formats, as noted in the detailed documentation for each method.

While many of the API methods access publicly available data, such as a certain brand’s most recent photos, other methods access or modify a user’s private data. For these cases, we use the same industry-standard OAuth2 system as Facebook to provide a safe, simple, secure way for Pongr users to grant access to your application. For example, if your app provides a way for a user to upload a photo to Pongr, your app must first obtain a special access token. Pongr will give your app this access token after checking with the user to make sure it’s OK. Then you just include that user’s access token along with the photo when you upload it. Learn more about Pongr’s OAuth2 system.


Here are the resources included in the API and the actions they support.

/photos

GET

Returns a list of photos that match the query parameters.

  • userId: optional, returns only photos that belong to this user
  • brandId: optional, returns only photos tagged with this brand
  • sort: optional, must be either recent or liked, recent is the default if not specified
  • start: optional, used with sort=like to only return photos created after this date/time, absolute or relative
  • end: optional, used with sort=like to only return photos created before this date/time, absolute or relative
  • limit: optional, returns a maximum of this number of photos, default is ?
  • after: optional, returns photos created after the specified date/time, useful for pagination
This is an extremely flexible method and provides a single endpoint for almost all photo query needs. Some examples follow:
  • Photohose (all recent photos) = GET /photos
  • User’s most recent photos = GET /photos?userId={userId}
  • User’s popular photos = GET /photos?userId={userId}&sort=liked&start=3days
  • Brand’s most recent photos = GET /photos?brandId={brandId}
  • Brand’s all-time most-liked photo = GET/photos?brandId={brandId}&sort=liked&limit=1

POST

* Uploads a new photo to Pongr.

Request headers:

  • Content-Type: multipart/form-data
  • Authorization: Bearer <OAuth2 access token>
Request form parameters:
  • brandId: the brand to tag in this photo (multiple brands supported in future)
  • photo: the jpeg-encoded bytes of the photo
  • description: optional, text description of the photo
  • latitude
  • longitude

/photos/{photoId}

GET

Returns details about the specified photo.

PUT

* Updates details about the specified photo. Note that only certain details are modifiable.

DELETE

* Deletes the specified photo from Pongr.


/photos/{photoId}/likes

GET

Returns the list of users that like this photo.

POST

* Authenticated user likes this photo.


/photos/{photoId}/comments

GET

Returns the specified photo’s comments.

POST

* Authenticated user comments on this photo.


/photos/{photoId}/comments/{commentId}

PUT

* Authenticated user edits the specified comment, if that user owns it.

DELETE

* Authenticated user deletes the specified comment, if that user owns it.


/users

GET

Search for users that match query parameters.


/users/{userId}

GET

Returns public information about the specified user.


/users/{userId}/likes/users

GET

Returns the list of users that the specified user likes.


/users/{userId}/likes/by-users

GET

Returns the list of users that like the specified user.


/users/{userId}/likes/brands

GET

Returns the list of brands that the specified user likes.


/users/{userId}/likes/photos

GET

Returns the list of photos that the specified user likes.


/users/{userId}/likes/users/{userId2}

GET

Returns whether or not userId likes userId2.


/users/{userId}/likes/brands/{brandId}

GET

Returns whether or not userId likes brandId.


/users/{userId}/likes/photos/{photoId}

GET

Returns whether or not userId likes photoId.


/users/{userId}/awards

GET

Returns the specified user’s awards.


/users/me

GET

* Returns the authenticated user’s private information.

PUT

* Updates the authenticated user’s information.


/users/me/feed

GET

* Returns the authenticated user’s social news feed.


/users/me/notifications

GET

* Returns the authenticated user’s notifications.


/brands

GET

Search for brands that match query parameters.


/brands/{brandId}

GET

Returns the specified brand’s public information and statistics.

PUT

* Updates the specified brand’s information. Requires special brand authorization.


/brands/{brandId}/likes

GET

Returns the list of users that like the specified brand.

POST

* Authenticated user likes the specified brand.


/brands/{brandId}/users

GET

Returns the list of users that have Pongr’d the specified brand.


/brands/{brandId}/store

GET

Returns the specified brand’s store information.


/brands/{brandId}/store/items

GET

Returns the list of items in the specified brand’s store.


/brands/{brandId}/store/items/{itemId}

GET

Returns the specified item’s information.


/brands/{brandId}/store/items/{itemId}/likes

GET

Returns the list of users that like the specified item.

POST

* The authenticated user likes the specified item.


/brands/{brandId}/store/items/{itemId}/comments

GET

Returns the specified item’s comments.

POST

* The authenticated user comments on the specified item.


/brands/{brandId}/store/items/{itemId}/redeem

POST

* The authenticated user redeems their brand points to obtain the specified item.