Psst: The Foursquare Push API Is Coming Out This Afternoon


Foursquare’s magical tool that will allow developers to build apps that can remind you to buy milk when you walk past the grocery store or notify you when a friend is in the area will be publicly released today, Betabeat has heard, just a few days ahead of Foursquare’s global hackathon.

Foursquare first gave out information on the Push API at its hackathon back in March, and some developers have been quietly testing it since then. It’s been a bumpy road, as the Foursquare engineering team iterates fast and hard, which sometimes means developer apps get broken along the way. “I’m sure you’ve been getting plenty of messages recently about changes to the way the Push API works,” server engineer Zack Sheppard wrote yesterday in an email to developers. “I’m sorry these have been coming so rapid-fire, but we’ve been trying to get the workings behind this API strong, consistent, and ready for our beta launch tomorrow.”

The engineering team has been listening closely to feedback from developers, as evidenced by some of the API’s last minute modifications. Foursquare expects the release of the Push API to happen this afternoon.

Some more wonky details from Foursquare, for those who are interested:

1) Reminder, that when we move the payload to be param values, the payloads will start being URL-encoded. Most libraries will automatically decode this into what you’d expect without you doing anything, but be sure to check so you don’t get a surprise

2) Due to not clearly warning about (1) + some issues pushing out the documentation, we’ve decided to delay the roll out to tomorrow, Wednesday.


It was asked if we could (as part of this change) move the “checkin” and “user” objects into two different parameters for Push API messages, rather than lumping them together. It’s a great idea, so while we’re ripping of bandages, we’re going to do that.
Starting Tuesday, the Push API POST messages will have two parameters: “checkin” and “user” containing the corresponding checkin and user objects (
For those of you on the Venue Push API — this doesn’t apply to you =)


Beginning tomorrow with the launch (expect it in the afternoon), we’re going to be sending out all of our pushes as follows. As you’ve heard, we’ve already started sending checkins as a parameter on a POST request. There also has been some discussion of including the user as a separate parameter on the request. We’ve decided that isn’t the clearest choice, however since we told everyone to prepare to support that last week, we’re going to leave it there for at least the next month so that you don’t have to scramble to update it.

As for the overall picture, our official pushes from tomorrow on will look like this: A POST request with a parameter called “checkin” will contain a url-encoded JSON object. This encoding is required to send POST parameters, and is automatically undone by most libraries. The checkin object itself will follow our structure outlined at and will include both a venue and user object. This way you now only have a single JSON object to fetch and decode when a push comes in, and we stay consistent with the rest of our API.

Psst: The Foursquare Push API Is Coming Out This Afternoon