Socialwg/Social API/Foursquare API

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