Socialwg/Social API/Foursquare API

From W3C Wiki
Jump to: navigation, search

The Foursquare API gives access to Foursquare's core functionality.

Overview

Foursquare is a service that lets users announce their presence at a venue ("check in"). They can build up a social graph on the service, or just announce their checkins on other services like Twitter or Facebook.

The Foursquare social graph requires two-way relationships, so all "friend requests" must be approved by the friend.

If users check into certain places at certain times, they can win badges from the system. For example, checking into multiple Italian restaurants can earn them a badge about Italian food.

Users can add tips to a venue. They can also make lists of venues, like "Best parks for running in Cleveland".

Users can also "follow" pages (for brands) or lists and get updates as they come in.

The API uses OAuth 2.0 for authentication.

The venues list is partially user-curated. Users can submit venues to the service as new businesses open or close; they can also create venues like "Gate 84" or "The Mission" that might be smaller or larger than a typical business. They can also add venues that are private, for example their own house or office.

Entities

User
A foursquare user. Has a unique ID, name, avatar, and counts of social graph and badges. https://developer.foursquare.com/docs/responses/user
Venue
A place that someone can check into. Restaurants, cafes, parks, etc. Includes geographical metadata (address, lat/long) as well as categories, hours, and counts of responses by users (e.g. likes). https://developer.foursquare.com/docs/responses/venue
Badge
An award given by the site to a user for doing some actions, such as checking into the same kind of venue multiple times. https://developer.foursquare.com/docs/responses/badge
Checkin
An activity where a user "checks into" a venue -- announcing his or her presence there. Other users can comment on or "like" the checkin. https://developer.foursquare.com/docs/responses/checkin
Tip
A comment about a venue, expected to be informative to other visitors. "Try the chicken." https://developer.foursquare.com/docs/responses/tip
List
A user-curated list of venues, like "Best BBQ joints in Austin". Other users can follow updates for the list. https://developer.foursquare.com/docs/responses/list
Update
Broadcast message from the system. https://developer.foursquare.com/docs/responses/update
Photo
A picture associated with a checkin (and thus a venue). https://developer.foursquare.com/docs/responses/photo
Special
A special deal that's only available to people who check into a venue. https://developer.foursquare.com/docs/responses/special
Event
An event at a venue; for example, a play at a theatre or a conference at a convention centre. Users can check into the "event" rather than the venue. https://developer.foursquare.com/docs/responses/event
Page
A user account with additional profile information, typically for a multi-venue brand (like Starbucks).

Endpoints

There are about 105 endpoints in the Foursquare API. Since Foursquare's single app was separated into two apps, the API endpoints are marked as part of "Foursquare" or "Swarm". There are also some endpoints that are deprecated.

Content management

Checkins

checkins/add
Check into a venue.
checkins/<id>
Get information about a checkin

Tips

tips/add
Create a tip
tips/<id>
Get information about a tip

Photos

photos/add
Add a photo to a checkin.
photos/<id>
Get information about a photo

Lists

lists/add
lists/items
lists/<id>
lists/additem
lists/deleteitem
lists/moveitem
lists/update
lists/updateitem
Create, read, update a list.

Venues

venues/add
Create a venue
venues/<id>
Get information about a venue.
venues/claim
Claim ownership of a venue (to get editing privileges)
venues/edit
Change a venue's data (privileged users only)
venues/events
venues/herenow
venues/hours
venues/links
venues/menu
venues/nextvenues
venues/photos
venues/similar
venues/stats
Extra data about a venue
specials/add
Add a special to a venue (privileged user only)
events/add
Add an event to a venue (privileged user only)

Outbox

users/checkins
users/lists
users/tips
users/photos
Content created by a user.
users/mayorships
users/tastes
users/venuehistory
users/venuelikes
Achievements by the user

Inbox

checkins/recent
Recent checkins by people you follow.

Responses

checkins/like
Like or unlike a checkin.
tips/like
Like or unlike a tip.
venues/like
Like or unlike a venue.
venues/dislike
Dislike a venue.
tips/unmark
checkins/addcomment
checkins/addpost
checkins/deletecomment
CRUD for comments on checkins. A "post" is a reply from a third-party application.
checkins/likes
Read who likes the checkin.
tips/likes
tips/listed
tips/saves
Response information about tips.
venues/likes
venues/listed
venues/tips
Response information about venues.
lists/suggestphoto
lists/suggesttip
lists/suggestvenues
Suggest content for another user's list
venues/proposeedit
Suggest changes for a venue.
lists/share
Share a list with your friends.
lists/saves
Show who's "saved" the list.

Social graph

users/friends
See who a user's friends are.
users/requests
Outstanding requests to become a user's friend.
users/approve
users/deny
Manage the outstanding friend requests.
users/unfriend
Remove a user from the friends list.
users/leaderboard
Friends ranked by who's earned more points for checkins.
users/setpings
Manage notifications of another user's checkins.

Content relationships

lists/follow
lists/unfollow
Follow or unfollow a list.
lists/followers

Profile

users/<user-id>
Get a single user's data.
users/badges
Badges earned by a user
users/update
Update the avatar and other user data.
settings/all
settings/set
Change how the application works, e.g. how it sends notifications to Twitter or Facebook.

Spam or other bad content

tips/flag
Flag a tip as offensive or spammy.
venues/flag
Flag a venue.
specials/flag
Flag a special

User search

users/search

Content search

events/search
specials/search
venues/search
venues/categories
venues/explore
venues/trending
Search for venues, events, or specials near a spot.

Other

TBD

Most of these are for brand managers, not for regular users.

venues/managed
venues/suggestcompletion
venues/timeseries
venues/setrole
venues/setsinglelocation
venuegroups/add
venuegroups/delete
venuegroups/list
venuegroups/timeseries
venuegroups/addvenue
venuegroups/edit
venuegroups/removevenue
venuegroups/update
updates/notifications
updates/marknotificationsread
specials/list
events/categories
pages/add
pages/managing
pages/access
pages/similar
pages/timeseries
pages/venues
pages/follow
pageupdates/add
pageupdates/list
pageupdates/delete
pageupdates/like
multi/multi

Example JSON

Below is a (truncated) example of a checkin object in JSON form from the API.

{
  "id":"56282702498e24896627ac1d",
  "createdAt":1445472002,
  "type":"checkin",
  "shout":"Homebrew Website Club!",
  "timeZoneOffset":-420,
  "user":{
    "id":"59164",
    "firstName":"aaronpk",
    "gender":"male",
    "relationship":"self",
    "photo":{
      "prefix":"https:\/\/irs1.4sqi.net\/img\/user\/",
      "suffix":"\/QREPPTELDVOJ5CE5.jpg"
    }
  },
  "venue":{
    "id":"5518748f498ec1c4b3e6ff9f",
    "name":"Cup & Bar",
    "contact":{
      "phone":"5033387701",
      "formattedPhone":"(503) 338-7701"
    },
    "location":{
      "address":"118 NE M L King Blvd",
      "lat":45.52398725868241,
      "lng":-122.66165710999158,
      "postalCode":"97232",
      "cc":"US",
      "city":"Portland",
      "state":"OR",
      "country":"United States",
      "formattedAddress":[
        "118 NE M L King Blvd",
        "Portland, OR 97232"
      ]
    },
    "categories":[...],
    "url":"http:\/\/www.cupandbar.com",
    "allowMenuUrlEdit":true,
    ...
  },
  "source":{
    "name":"Swarm for iOS",
    "url":"https:\/\/www.swarmapp.com"
  },
  ...
}

See Also