Foursquare API Getting Started: Quickstart Guide (2026)

Getting started overview

This guide provides a focused walkthrough for developers to initiate interaction with the Foursquare API. It covers the essential steps from account creation and credential acquisition to executing a basic API request. The Foursquare API enables developers to integrate location intelligence into their applications by providing access to a database of places and associated data (Foursquare Developer Documentation). Successful completion of these steps will confirm your setup is correct and ready for further development.

The core process involves:

1. Registering for a Foursquare Developer account.
2. Creating a new application within the developer portal to obtain API keys or set up OAuth 2.0 credentials.
3. Making an authenticated request to a Foursquare API endpoint.

Understanding the distinction between API key authentication and OAuth 2.0 is crucial. API keys are suitable for server-side applications where the key can be kept secure. OAuth 2.0 is designed for user-facing applications where users grant permission for your application to access their data without sharing their personal credentials (OAuth 2.0 specification). For initial testing and many server-side integrations, API key authentication is often simpler to implement.

Quick Reference Steps

Create an account and get keys

To begin, navigate to the Foursquare Developer Portal. If you do not have an account, you will need to register. The registration process typically involves providing an email address, creating a password, and agreeing to the terms of service (Foursquare API Terms of Service).

1. Sign Up/Log In: Go to the Foursquare Developer Portal and either sign up for a new account or log in with existing credentials.
2. Create a New Application: Once logged in, locate the section for managing your applications. This is typically labeled something like "My Apps" or "Create New App." Click to create a new application.

   When creating your application, you will be prompted to provide details such as:

   • Application Name: A descriptive name for your project.
   • Application Description: A brief explanation of what your application does.
   • Callback URL(s): Essential for OAuth 2.0 flows, but can often be left blank or set to a placeholder for API key-based testing.
   • Type of App: Select the category that best describes your application (e.g., web app, mobile app, internal tool).
3. Retrieve API Keys: After successfully creating your application, the developer portal will display your unique credentials, typically a Client ID and a Client Secret. These are your API keys. Treat your Client Secret as a sensitive piece of information, similar to a password. Do not expose it in client-side code, public repositories, or unsecured environments.

For applications that require user authentication, Foursquare uses the OAuth 2.0 protocol. This involves redirecting users to Foursquare to authorize your application, after which Foursquare redirects them back to your specified callback URL with an authorization code. This code is then exchanged for an access token, which is used for subsequent API requests on behalf of the user (Foursquare OAuth 2.0 Guide).

Your first request

With your API keys (Client ID and Client Secret) in hand, you can now make your first Foursquare API call. For this example, we will use the Places Search endpoint to find venues near a specific location. This is a common starting point for integrating Foursquare's location data.

The Foursquare API base URL for the Places API is https://api.foursquare.com/v3/places/.

Authentication Parameters

For most Foursquare API v3 endpoints, authentication is performed by including your API key (Client Secret) in the Authorization header of your HTTP request. The header format is Authorization: YOUR_CLIENT_SECRET.

Example Request (cURL)

This cURL command demonstrates how to search for coffee shops near New York City. Replace YOUR_CLIENT_SECRET with your actual Client Secret.

curl --request GET \
     --url 'https://api.foursquare.com/v3/places/search?query=coffee&ll=40.730610,-73.997699&limit=5' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_CLIENT_SECRET'

Explanation of parameters:

• query=coffee: Searches for venues categorized or named 'coffee'.
• ll=40.730610,-73.997699: Specifies the latitude and longitude (New York City) for the search.
• limit=5: Limits the number of results returned to 5.
• Accept: application/json: Requests the response in JSON format.
• Authorization: YOUR_CLIENT_SECRET: Your API key for authentication.

Example Request (Python)

Here's how to achieve the same request using Python's requests library:

import requests
import os

# It's recommended to store your client secret in environment variables
CLIENT_SECRET = os.getenv('FOURSQUARE_CLIENT_SECRET')

url = "https://api.foursquare.com/v3/places/search"

params = {
    "query": "coffee",
    "ll": "40.730610,-73.997699",
    "limit": 5
}

headers = {
    "Accept": "application/json",
    "Authorization": CLIENT_SECRET
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")

Before running the Python example, ensure you have the requests library installed (pip install requests) and that you have set the FOURSQUARE_CLIENT_SECRET environment variable to your actual Client Secret.

Common next steps

Once you have successfully made your first API call, consider the following common next steps to further integrate and optimize your use of the Foursquare API:

1. Explore Other Endpoints: The Foursquare API offers various endpoints beyond basic search, including detailed venue information, photos, tips, and categories. Refer to the Foursquare API Reference to discover more functionalities that can enhance your application.
2. Implement Error Handling: Robust applications should gracefully handle API errors. The Foursquare API returns standard HTTP status codes for different error conditions (MDN HTTP Status Codes). Implement logic to check the status code and parse error messages from the JSON response.
3. Manage Rate Limits: Be aware of Foursquare's API rate limits to prevent your application from being temporarily blocked. Monitor response headers for information on your current rate limit status and implement retry mechanisms with exponential backoff if limits are hit. Details on rate limits are typically found in the Foursquare Developer documentation on rate limits.
4. Secure Your Credentials: For production environments, ensure that your Client Secret is never hardcoded or exposed. Use environment variables, secure configuration files, or a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager) to store and retrieve sensitive information securely.
5. Switch to OAuth 2.0 (if applicable): If your application requires users to authenticate and grant access to their Foursquare data, transition from simple API key authentication to an OAuth 2.0 flow.
6. Consider SDKs/Libraries: While Foursquare does not provide official SDKs, community-contributed libraries in various programming languages can simplify interaction with the API. Search GitHub or package managers for "foursquare api client [your-language]".
7. Monitor Usage: Regularly check your API usage statistics within the Foursquare Developer Portal to ensure you stay within your plan's limits and understand your application's behavior.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check API Keys: Double-check that your Client Secret (API key) is correct and has not been truncated or altered. Ensure there are no leading or trailing spaces. The most common error is an invalid or expired API key.
• Verify Authorization Header: Confirm that the Authorization header is correctly formatted as Authorization: YOUR_CLIENT_SECRET.
• Review Endpoint URL: Ensure the URL for the API endpoint is correct, including the version (e.g., /v3/places/search). Typographical errors in the URL can lead to 404 Not Found errors.
• Inspect Parameters: Verify that all required query parameters are present and correctly formatted. For example, latitude and longitude (ll) should be a comma-separated pair of numbers.
• Check HTTP Status Codes: The HTTP status code in the API response provides critical information:
  • 400 Bad Request: Often indicates missing or malformed parameters.
  • 401 Unauthorized: Usually means an invalid or missing API key/credentials.
  • 403 Forbidden: Your application may not have the necessary permissions for the requested resource, or you've hit a rate limit.
  • 404 Not Found: The requested endpoint or resource does not exist.
  • 429 Too Many Requests: You have exceeded your rate limits.
  • 5xx Server Error: Indicates an issue on the Foursquare server side.
• Examine Response Body: Even with an error status code, the response body often contains a JSON object with a detailed error message that can pinpoint the exact problem.
• Consult Documentation: Refer to the specific endpoint's documentation in the Foursquare API Reference for expected parameters and error codes.
• Network Issues: Ensure your development environment has an active internet connection and no firewall rules are blocking outgoing requests to api.foursquare.com.
• Environment Variables: If using environment variables (as in the Python example), verify they are correctly set in your shell before running the script.