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:
- Create a developer application. These will be your privileged credentials when using the Foursquare API.
- Find the venue on Foursquare. If the venue doesn’t exist, add the venue.
- 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.
- Visit the Foursquare for Developers website and click on “My Apps” in the navigation bar.
- 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.
- Send us the API client ID of your developer application to [email protected].
- 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
| 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 |
| 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!
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
| 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 |
| 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 |
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.
| 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 [email protected]. 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: