Harmonization

🛠️

Public Beta Feature

This documentation covers a feature currently in Public Beta. Access is available to anyone interested in building personalized experiences for their end-users.

This feature is subject to the Personalization API (Self-Service) Public Beta End user License Agreement 📄.

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.

Create 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 [email protected].
  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.

Find 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
ParameterDescriptionRequired
vThe date that represents the version of the API from Foursquare. Example: 20160601Yes
oauth_tokenThe OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Yes
intentThis should be set to match in order to find the best possible result.Yes
nameThe name of the business. Example: Foursquare HQYes
llThe geographical coordinates (latitude and longitude) of the business. Example: 40.72412842453194,-73.99726510047911Yes
addressThe street address of the business. Example: 568 BroadwayNo
cityThe city of the business. Example: New York CityNo
stateThe state (or province) of the business. Example: NYNo
zipThe zip code (or postal code) of the business. Example: 10012No
phoneThe phone number of the business. Example: 2125551212No
twitterThe Twitter handle of the business. Example: foursquareNo

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!

Add 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
ParameterDescriptionRequired
vThe date that represents the version of the API from Foursquare. Example: 20160601Yes
oauth_tokenThe OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4Yes
nameThe name of the business. Example: Foursquare HQYes
llThe geographical coordinates (latitude and longitude) of the business. Example: 40.72412842453194,-73.99726510047911Yes
primaryCategoryIdThe primary category ID of the business. Example: 4bf58dd8d48988d125941735Yes
addressThe street address of the business. Example: 568 BroadwayNo
crossStreetThe cross street (or intersection) of the business. Example: at Prince StNo
cityThe city of the business. Example: New York CityNo
stateThe state (or province) of the business. Example: NYNo
zipThe zip code (or postal code) of the business. Example: 10012No
phoneThe phone number of the business. Example: 2125551212No
twitterThe Twitter handle of the business. Example: foursquareNo
descriptionThe description of the business, up to 300 characters.No
urlThe website URL of the business. Example: https://foursquare.comNo

Create 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.

ParameterDescriptionRequired
vThe date that represents the version of the API from Foursquare. Example: 20160601yes
providerIdThe unique provider ID that you received from Foursquare by emailing [email protected]. Example: foursquareyes
linkedIdThe unique ID of the listing that is used internally. Example: A1B2C3D4E5yes
oauth_tokenThe OAuth access token that you received when authorizing your user account against your developer application. Example: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0U1V2W3X4yes

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: