Proximity Set Format/Upload

Foursquare's Proximity Designer provides complete access to our Global Places Data to create geofences based on millions of businesses and points of interest around the world. However, many customers have campaigns that require custom data that may not be easily accessible in Foursquare's global places data.

Foursquare currently supports uploads of two different types of files: (1) geocoded points (latitude, longitude) and (2) custom polygons. Note that polygon uploads are now supported in both Audience Designer and Proximity Designer.

Additionally, Foursquare does not accept lists of addresses without geocoded latitude and longitude coordinates. Please contact Partner Services if you need geocoding services.

To upload custom location data for use in Proximity or Audience, follow the instructions below.

Point Upload (lat/long)

Uploaded files must contain valid latitude and longitude coordinates for each location. Acceptable file formats include CSV, TSV, and Excel. The easiest way to start is to download one of our sample templates and modify those.

Download Sample Templates here: CSV, TSV, or Excel

latitudelongitudename
34.073011-118.376097The Coffee Bean and Tea Leaf
34.098155-118.329646Groundwork Coffee Company
34.003545-118.484834Peet’s Coffee and Tea
34.008187-118.491283Cora’s Coffee Shop

File Format Checklist

  • The following file formats are acceptable:
    • Comma Separated Values (.csv)
    • Tab Separated Values (.txt, .tsv, or .tab)
    • Excel (.xlsx or .xls)
  • The first row of the file must be a header that includes the following labels:
  • latitude
  • longitude
  • name (optional)
    • Name is an optional identifier primarily to help you understand the locations that you have uploaded on the Proximity Designer map, but it will not affect the final Proximity targeting file.
  • Each row of the file must include latitude and longitude.
  • Files of up to 5 MB are accepted
  • This corresponds to roughly 100,000 rows, though file size varies with the file type and how the data is formatted
  • If you have a need to upload a larger file, please contact Partner Services.

Post-Upload Guidelines

  • In the UI you can change the following parameters for each uploaded file:
  • Set Name
  • Targeting Code
  • Radius
  • If you wish to use a different radius for the same data, simply upload the dataset again as a new set
  • Currently, the Proximity Designer UI will only show the first 1000 rows from your uploaded data on the map. Actual targeting files will contain all points in the uploaded file, however.
  • A Proximity Set based on an uploaded location file can be used to design an Audience like any other Proximity Set.

Polygon Upload

Note: Polygon upload now works in both Audience Designer and Proximity Designer. To get access to this feature, please contact Partner Services.

Uploaded files must contain valid polygon data, formatted as WKTs or GeoJSON objects. The easiest way to start is to download one of our sample templates and modify those.

Download Sample Templates here: WKT, GeoJSON

WKT File Format Checklist

We recommend using WKTs in your polygon file uploads.

  • Headers are optional, but can only contain the following values: ‘name’, ‘polygon’, ‘coordinates’
  • File must have at least one line
  • Each non-header line must contain a WKT polygon and can contain a name
  • Columns should be tab separated (.txt, .tsv, or .tab)
  • Files of up to 5 MB are accepted
  • If you have a need to upload a larger file, please contact Partner Services.
name (optional)polygon
polygon 1POLYGON((lng1 lat1, lng2 lat2, lng3 lat3, lng4 lat4, …))
polygon 2POLYGON((lng1 lat1, lng2 lat2, lng3 lat3, lng4 lat4, …))

GeoJSON File Format Checklist

Polygon upload also supports GeoJSON data. Valid GeoJSON must represents a FeatureCollection where each feature is a Polygon with:

  • Exactly one linear ring (i.e. no cutouts or doughnut-type shapes)
  • Coordinates that are valid geospatial points
  • Area between 24,000m^2 and 2,827,400,000m^2
  • An optional name property for use in the designer display

Sample Schema

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": {(Optional) name string 1}
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [ [ ...{Polygon 1 Coordinates} ] ]
      }
    },
    {
"type": "Feature",
"properties": {
    "name": {(Optional) name string 2}
},
"geometry": {
    "type": "Polygon",
    "coordinates": [ [ ...{Polygon 2 Coordinates} ] ]
}
    }
  ]
}

Post-Upload Guidelines

In the UI you can change the following parameters for each uploaded file:

  • Set Name
  • Targeting Code
  • Currently, the Proximity Designer UI will only show the first 1000 rows from your uploaded data on the map. Actual targeting files will contain all polygons in the uploaded file.