Foursquare Intersections logo
Data & Tech

A New Experience for Developer Documentation & Resources

Written by Arin Ray on Nov 21, 2017 - Read time: 3 min - Read Later

Foursquare Developer documentation

Documentation is one of the most important aspects in building a strong developer community. Earlier this year we launched an entirely new version of, packed with features to help developers get started and explore our location intelligence tools.

In addition to updating the site's branding, our team overhauled the existing documentation. A month since launch, we're excited to talk about how we built it, and share some of our learnings in this post. We'll first discuss infrastructure changes and then delve into some features.


Here is a breakdown of our developer documentation infrastructure.

Content Management

Upon approaching a redesign, we explored a number of technologies before settling on the Jekyll framework. This helps us transform markdown documents into a reusable documentation platform. Additionally, we added some custom plugins to make it easier and faster for us to update our documentation.


We run a simple script to build an image from our Dockerfile and expose our pages via a Nginx web server. Ngnix also handles the redirects from our old documentation URLs to the new ones.


Builds are automatically picked up on-commit from master via Travis-Ci and trigger the deployment process. This decouples our docs from everything else, and allows for us to push live updates in a matter of minutes.


Here are some of the major feature improvements:

  • Search
  • Endpoint Pages
  • Sample Apps & Libraries


We built a search engine using ElasticSearch so developers can find keywords, specific endpoints, error responses, etc. It's also reindexed every time we push an update to our docs site. We added this functionality with the future in mind, creating an API that will allow us to integrate into 3rd parties seamlessly. This makes integrating directly into IDEs like Xcode and Android Studio simple.

Foursquare Developer documentation

Endpoint Pages

Endpoint pages now have API responses! This makes it simple and easy for developers to see the expected output from our endpoints. These are programmatically generated to make sure we always display the right response.

endpoint pages for Foursquare Places API

Sample Apps & Libraries

We added several Sample Apps to showcase the power of our API such as picking a spot to hail a ride, finding the closest coffee shop, and even exploring the real world through Augmented Reality. There are also a couple new Client Libraries we added featuring support for newer languages like Swift and Go.

We're looking to continually improve and expand these pages. In case you have a library or app you would like featured, feel free to drop us a note!

sample apps & libraries

augmented reality + Foursquare Places API

Looking Forward

Haven't used our API before? No problem! We have a new getting started guide that'll help you create an account and make your first API call in 5 easy steps.

We also plan on continuously improving our developer experience! Stay tuned for updated visuals to our API explorer and app signup pages.

Have feedback for us? We'd love to hear from you! Feel free to reach out to us @FoursquareAPI.


Follow Arin Ray

A New Experience for Developer Documentation & Resources

Read Later

Pardot response heading