Venue Harmonization

A major part of our Venues Project is building a comprehensive Venue Harmonization Map. Right now, there’s no Rosetta Stone for location, allowing you to link information about a real-world place from one database to any other.

For instance, if you look up a restaurant in the foursquare API, we give you our ID number for that location. But if you were to look up the same restaurant in The New York Times or MenuPages, they’d have a different ID number in their database. The Venue Harmonization Map aims to solve that, by translating those numbers so that you only have to look up the ID once. So, for instance, if you know the URL of a restaurant on Thrillist, you can find that same restaurant in our database. And the other way works, too! (Here’s an example.)

The goal of foursquare’s Venue Harmonization Map is to translate between these databases, making it easier to create mash-ups, link to pages on other sites, or add foursquare widgets like “Add to foursquare” to publisher sites.

For practical reasons, we’re not able to harmonize against every single other database in existence. We are currently harmonizing location platforms (E.g. over 500,000 listings and an API) and major content providers (over 100,000 listings with significant content associated with each listing). For other sites, we recommend calculating a local mapping between your database and foursquare’s, which will allow you to easily access foursquare data, as well as the data of our harmonization partners.


Step 1: Registering an API consumer

Register an API consumer for your site/application at https://foursquare.com/developers/apps, if you haven’t already. This will give you a unique client_id & client_secret which you will need when making requests to our API.


Step 2: Calculating the the venue mapping

The venue mapping process is a sequential one — you pass a business name + geolocation to us, and we return a matching location from our database, if we can find one. In more technical terms, you’ll make a request to our /venues/search API endpoint specifying that you have an intent to match and we’ll return at most 1 search result.

If you were New York Magazine, looking to match the beauty boutique Creed, this request would look like:

        https://api.foursquare.com/v2/venues/search
          ?intent=match
          &ll=40.768853,-73.967792
          &query=Creed
          &client_id=YOUR_CLIENT_ID
          &client_secret=YOUR_CLIENT_SECRET
        

Using our API Explorer, you can see what the output for this request would be. In this case, the request matched with Creed Boutique, with foursquare venue ID: 4c13b4697f7f2d7ffd7ddf68.

By default you can make up to 5,000 requests per hour to our API. If you send your client_id to api@foursquare.com we can increase your rate limit to an appropriate value.

Step 2.5: Adding missing venues

If your request didn't return a match, it may be that foursquare doesn't have a corresponding venue. You can create a foursquare venue for the business via the venues/add endpoint.


Step 3: Harmonizing / Pushing the mapping back

For major partners and platforms, foursquare would like to store the mapping you’ve calculated so that third-party developers can benefit from the coupling of our data. If this applies to you, please e-mail us at api@foursquare.com and we will white-list your client_id for harmonization and give you a providerId, which will identify your mapping data in our database.

To report your mapping back to us, we have a special endpoint: /venues/VENUE_ID/annotate where VENUE_ID is the foursquare venue ID you’re mapping to.

Using the results from our example above, the annotate request (made using the POST method) looks like:

        POST:
          https://api.foursquare.com/v2/venues/4c13b4697f7f2d7ffd7ddf68/annotate
        Fields:
          providerId=YOUR_PROVIDER_ID
          linkedId=59455
          url=http://nymag.com/listings/beauty/creed/index.html
          client_id=YOUR_CLIENT_ID
          client_secret=YOUR_CLIENT_SECRET
        

For this request, you’ll use the providerId we gave when you registered your client_id with us earlier. The linkedId should be the unique ID for the venue in your database. There is an optional url parameter for linking to a corresponding page inside of your site for that venue.

If you wish to confirm that your mapping was added, call /venues/search again, with your linkedId.

        https://api.foursquare.com/v2/venues/search
          ?providerId=YOUR_PROVIDER_ID
          &linkedId=59455
          &client_id=YOUR_CLIENT_ID
          &client_secret=YOUR_CLIENT_SECRET
        

As before, you can use the API Explorer to preview the results of this request.