Jump to:

Overview

The process of venue harmonization on Foursquare is fairly simple! All actions associated with this process will be done through the Foursquare API. In general, these are the steps that need to be taken:

  1. Create a developer application. These will be your privileged credentials when using the Foursquare API.
  2. Find the venue on Foursquare. If the venue doesn’t exist, add the venue.
  3. Keep a mapping of your ID to the associated Foursquare venue ID, or annotate your ID directly to the Foursquare venue.

Creating a Developer Application

First things first, you will need to register for a Foursquare developer application, which will allow you to submit your listings to Foursquare. Follow the below steps to create a new account and register your application.

  1. Visit the Foursquare for Developers website and click on “My Apps” in the navigation bar.
  2. At the application dashboard, click on “Create a new app” and fill in the appropriate details. After this step, you should have a new developer application listed.
  3. Send us the API client ID of your developer application to api@foursquare.com.
  4. Now, you’ll need to obtain your OAuth access token by authenticating your user account against your developer application. Refer to our documentation on authentication. Make a note of your OAuth access token, as you will need it to interact with the Foursquare API.

At this point, you should have access to your Foursquare user account, and have your Foursquare API client ID and Foursquare user OAuth token.


Finding Venues on Foursquare

Before you can create a mapping, you’ll need to have the ID of the venue that you want to interact with. We recommend that you check if the venue already exists on Foursquare before creating a new venue.

To find a venue on Foursquare, you can use the venues/search API endpoint. In order to perform a thorough search, we require that you have the name and geographical coordinates (latitude and longitude) of the venue. To provide better search results, we also accept the following as additional attributes: street address, city, state, zip, phone number, or Twitter handle.

GET https://api.foursquare.com/v2/venues/search
Parameter Description Required
v The date that represents the version of the API from Foursquare. Example: 20160601 Yes
oauth_token The OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4 Yes
intent This should be set to match in order to find the best possible result. Yes
name The name of the business. Example: Foursquare HQ Yes
ll The geographical coordinates (latitude and longitude) of the business. Example: 40.72412842453194,-73.99726510047911 Yes
address The street address of the business. Example: 568 Broadway No
city The city of the business. Example: New York City No
state The state (or province) of the business. Example: NY No
zip The zip code (or postal code) of the business. Example: 10012 No
phone The phone number of the business. Example: 2125551212 No
twitter The Twitter handle of the business. Example: foursquare No

The above API request will return a response in JSON. If the venue exists on Foursquare, the response will include a venue object, which includes the venue ID. Keep this venue ID handy as it’s the unique identifier for the specific location you searched!


Adding Venues on Foursquare

If you’re unable to find the venue, you’ll need to add it to Foursquare. In order to do so, you can use the venues/add API endpoint. We require that you have name, category, and geographical coordinates (latitude and longitude) of the venue. For categories, you can refer to the Foursquare Category Hierarchy or use the venues/categories API endpoint.

GET https://api.foursquare.com/v2/venues/add
Parameter Description Required
v The date that represents the version of the API from Foursquare. Example: 20160601 Yes
oauth_token The OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4 Yes
name The name of the business. Example: Foursquare HQ Yes
ll The geographical coordinates (latitude and longitude) of the business. Example: 40.72412842453194,-73.99726510047911 Yes
primaryCategoryId The primary category ID of the business. Example: 4bf58dd8d48988d125941735 Yes
address The street address of the business. Example: 568 Broadway No
crossStreet The cross street (or intersection) of the business. Example: at Prince St No
city The city of the business. Example: New York City No
state The state (or province) of the business. Example: NY No
zip The zip code (or postal code) of the business. Example: 10012 No
phone The phone number of the business. Example: 2125551212 No
twitter The Twitter handle of the business. Example: foursquare No
description The description of the business, up to 300 characters. No
url The website URL of the business. Example: https://foursquare.com No

Creating a Mapping from Harmonization

Once you have the Foursquare venue ID that corresponds with your listing, you will now have to save the mapping to reference to for future use. There are two main options here - either store the mapping internally, or use Foursquare API to annotate your ID to the venue. To annotate your ID to a venue on Foursquare, you can use the ​venues/annotate​ API endpoint. You’ll need to get in contact with us first before using this method, in order to reserve a unique provider ID for your use.

Parameter Description Required
v The date that represents the version of the API from Foursquare. Example: 20160601 yes
providerId The unique provider ID that you received from Foursquare by emailing api@foursquare.com. Example: foursquare yes
linkedId The unique ID of the listing that is used internally. Example: A1B2C3D4E5 yes
oauth_token The OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4 yes

Best Practices and Style Guides

Before uploading any data to Foursquare, we recommend that you prepare your data, so that it aligns with our Editing Guidelines and Style Guide. Within the style guide, we have a list of guidelines and policies that help us maintain a high-quality and consistent dataset. This minimizes the number of data conflicts and ensures your edits will update without any issues.


Global Style Guide


Regional Style Guides

In addition to the Global Style Guide, each region may have nuances in the preferred styles that all editors must follow. Find your region’s style guide below:

Was this page helpful?
Yes
No
Thank you!