Real Time View

These APIs allow your application to get a real-time view into various actions on Foursquare. The User Push API lets you know whenever one of your authenticated users checks in, and the Venue Push API will ping you whenever certain actions happen at your users’ managed venues. These APIs follow a webhook model and send an HTTP request to your servers whenever one of these actions occur.

User Push API

The User Push API will push to your application every time one of your users checks in (these users must have previously authorized your application). Your server will receive a POST request containing a checkin parameter. Inside the checkin parameter will be a normal check-in response, rendered from your user's point of view.

Venue Push API

This API is designed for applications whose users are managers of venues, allowing the application to get a real-time view of activity at their venues. The Venue Push API will push to your application content from venues managed by any of your application's authorized users (or at a home venue that was created by one of your application's authorized users). Supported venue content are check-ins, likes, tips, and photos at the venue.

It's important to stress that in order for your app to see pushes for a venue, at least one of this venue's managers must have authorized use of your app, otherwise you may see “Your app can't see pushes from that venue” errors.

Whenever a Foursquare user creates new content at a venue that your users manage, your server will receive a POST request containing a parameter corresponding to the content:

Inside this parameter will be a compact check-in, like, tip, or photo object. A difference between this and the User Push API is that these responses will have been generated from an anonymous point of view, meaning that some private information, such as shouts, will not be included. Additionally, off-the-grid check-ins, cheat check-ins, and check-ins by users who have opted out of venue statistics collection are not sent to this API.

Activating real-time APIs

Before you begin

To receive real-time notifications, you will need to have a server that accepts HTTPS connections on the default port (443). Self-signed certificates are fine, but will cause users to see warnings if they try to visit your site via HTTPS. You can check the validity of your security certificates using DigiCert's SSL certificate checker tool.

Privacy

HTTPS is required for all real-time APIs because your application will receive check-ins (both public and private), user information, and other private information along this channel. Your application is trusted with this information by the user, and we expect you not to violate that trust.

Your application is expected to not share, retransmit to third parties, retransmit unsecurely, or cache indefinitely any information we transmit to you. Also, remember that applications on the User Push API will receive all check-ins—public, friend restricted, and private—by that user. Respect your user's privacy. For more, review our Platform Policy.

Activating real-time for your consumer

To turn on real-time APIs for your consumer, access your consumer's details page by clicking on its name at https://foursquare.com/developers/apps. Then click the “Edit This App” button in the upper right of the page.

To change your consumer's real-time API settings, pick the desired state from the drop-down menu on that page titled “Push API notifications.” Enter the (HTTPS-compliant) URL you want to receive pushes at. Then click “Save Changes.” You should now see your new notification settings reflected on the details page for your consumer.

Format of real-time pushes

A "push" is basically just an HTTP POST request we send to your Push URL whenever an action relevant to your application occurs (e.g., one of your users checks in).

The POST request contains a JSON payload that arrives URL-encoded, just as if it was created by a normal HTML form element. Each payload contains three parameters:

Sample push

Here is a sample push for a check-in by Jimmy Foursquare at Foursquare HQ.

This push was generated by the User Push API, but the Venue Push API is almost identical. Inside of the checkin parameter will be JSON similar to the following.

{
  "id": "4e6fe1404b90c00032eeac34",
  "createdAt": 1315955008,
  "type": "checkin",
  "timeZoneOffset": -240,
  "user": {
    "id": "1",
    "firstName": "Jimmy",
    "lastName": "F",
    "photo": "https://foursquare.com/img/blank_boy.png",
    "relationship": "self"
  },
  "venue": {
    "id": "4ab7e57cf964a5205f7b20e3",
    "name": "foursquare HQ",
    "contact": {
      "twitter": "foursquare"
    },
    "location": {
      "address": "East Village",
      "lat": 40.72809214560253,
      "lng": -73.99112284183502,
      "city": "New York",
      "state": "NY",
      "postalCode": "10003",
      "country": "USA"
    },
    "categories": [
      {
        "id": "4bf58dd8d48988d125941735",
        "name": "Tech Startup",
        "pluralName": "Tech Startups",
        "shortName": "Tech Startup",
        "icon": "https://foursquare.com/img/categories/building/default.png",
        "parents": ["Professional & Other Places", "Offices"],
        "primary": true
      }
    ],
    "verified": true,
    "stats": {
      "checkinsCount": 7313,
      "usersCount": 565,
      "tipCount": 128
    },
    "url": "http://foursquare.com"
  }
}

If you'd like to quickly play with the push API in the wild and see real pushes from us without having to set up server-side infrastructure, we recommend using RequestBin. Create a new bin and set that URL as your push URL. After authenticating users and performing the correct actions (e.g., checking in), you should see Foursquare pushes to your bin.

Push sources

Pushes originate from the following IP address blocks. If your server is behind a firewall, you must whitelist the IP range 199.38.176.0/22 in order to receive pushes.

Timeouts

A push request will timeout if it takes too long for your app to return a 200 OK to Foursquare's POST request, and this will be recorded as a push failure. If you're doing some time-consuming processing as soon as you receive Foursquare's POST, consider doing that work asynchronously and immediately return a 200 OK to us so that we don't record this push as an error.