Real-Time API

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. If you want a broader look at check-ins, you may be interested in a real-time stream of anonymous global check-ins instead.

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:

Content Parameter Description
Check-in checkin Whenever somebody checks in at the venue
Like* like Whenever somebody like the venue
Tip added* tip Whenever somebody leaves a tip at the venue
Photo added* photo Whenever somebody leaves a photo at the venue (whether through a check-in, tip or a generic photo/add call

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.

*Your application will only receive pushes for these content types if you specify a push API version >= 20131118.

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 full API 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.

Versioning

We may occasionally need to change the push API's functionality or response format. Once you've registered your app for pushes, you can specify a Push version to protect yourself against changes and take advantage of newer features, such as likes, tips, and photos in the Venue Push API. For more details, see our general documetation on versioning.

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:

Parameter Type Description
user Object Contains information about the user that generated the action
One of checkin, like, tip, or photo Object This compact object will vary depending on the action that triggered the push. Only checkins will be pushed to you if you're subscribed to the User Push API.
secret String Your push secret. You can find and reset, if necessary, your push secret on your consumer's details page. This secret is provided so that you can verify the authenticity of pushes received (i.e. that they came from Foursquare rather than another source), provided you have kept your push secret a secret.

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": "Foursquare",
        "photo": "https://foursquare.com/img/blank_boy.png",
        "gender": "male",
        "homeCity": "New York, NY",
        "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 these ranges in order to receive pushes

  • 23.23.190.0/23
  • 107.23.0.0/23

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.