Proximity

Proximity is a high-volume, low latency server-side geofencing solution. It allows advertisers and developers to validate at high-speed millions of coordinate pairs against thousands of geographic point and polygon geofences. Queries are under performed will under one millisecond each, permitting twenty-thousand point-in-polygon queries-per-second on a standard, four core server.

309

Run 20,000 QPS on a standard four core server

Proximity is a server-side solution, run on your servers; it does not require an SDK or an on-device presence. We provide an interface tool for you to identify and design global geofences on Foursquare's 90 million+ businesses in over 50 countries. Multiple geofences are compiled into a single Proximity Proximity Set; each filter can contain up to 750,000 geofences each.

This document provides further detail on Proximity and the high-volume geofencing workflow it enables.

628

How It Works

The process is asynchronous and straight-forward:

639
  1. Install On-Prem on your infrastructure.
  2. Create geofences based point-radius or polygons with our Proximity Designer built on Foursquare's Global Places Data, which supports geofencing by business name, category, or merchant chains. Alternatively, use your own shapefiles or spatial data. We convert the geofences to an optimized binary format called a ‘Proximity Set’.
  3. The Proximity Set is automatically uploaded to your on-premise Proximity implementation; no restart is necessary.
  4. Validate geolocation queries against On-Prem.
  5. The service returns a JSON data packet describing what Proximity Sets the input coordinate pair satisfies.

Geofence Creation

Foursquare's Proximity Designer provides an easy way to find specific businesses – search by parameters including business type, chain name, and location.

418

Use the Proximity Designer to create geofences around specific places, or place-types

If you have your own data or data licensed from a third party, Foursquare can convert custom polys and any GeoJSON file into a Proximity Set.

Proximity Set Generation

The power of Proximity is not in geofence creation, but rather in our optimized data format that allows massive, server-side query throughput. This takes polygons, point/radius circles, or a combination of both, and optimizes the geographies for querying at the byte level.

Each Proximity Set may contain many hundreds-of-thousands of individual geofences: add all ‘McDonalds’ locations with a 1 km radius into a single filter and the system will continue to perform to spec. Thousands of geofences compress into binary format optimized for the Proximity code.

When complete, Filters are uploaded to your Proximity implementation transparently.


Implementation Overview

We’ve designed the system to be easy to integrate, and optimized for speed, simplicity, and compactness. It is highly encapsulated with few dependencies.

The Proximity service does not need to be restarted when new sets are added. If enough memory has been allocated (as specified in the config file), the new configuration will be automatically loaded.

Build a Proximity Set with Foursquare

Create a Proximity Set on Foursquare or ask us to help – this could be something like:

  • All Home Depots in Mexico
  • All Walgreens locations in three specific DMAs
  • 500m radius around every landmark in Britain, France, and Germany
  • All global airports
  • Major stadium and sporting venues in Europe

Foursquare Creates Proximity Sets

For each Proximity Set, Foursquare creates a binary file that contains one or more geofences. For the Walgreens example above, we might produce three files, one for each DMA:

  • walgreens-PHILADELPHIA-dma.index
  • walgreens-LOS_ANGELES-dma.index
  • walgreens-SAN_FRANCISCO-OAK-SAN_JOSE-dma.index

Each file contains multiple geofences in a highly optimized binary data structure.

Run on Your Infrastructure, On-Premises Proximity runs on your infrastructure within a container called On-Prem. You are free to duplicate it across as many nodes and cores as required.

For each point, if it satisfies a Proximity Set (a ‘hit’), we return the name(s) assigned to the associated Proximity Sets(s) and the accompanying contextual information, or FALSE if it fails to satisfy any of the Proximity Sets.


Proximity Ad-Serving Workflow

The typical Proximity workflow is one where media planners create filters on Foursquare Place data, and implement those filters locally as soon as possible thereafter. It looks something like this:

635

In the diagram above, the steps can be articulated as:

  1. Media Planner queries Foursquare Places data by name, chain, or business category, and assigns a geofence radius in meters via the Proximity Designer
  2. The Designer estimates impression capacity (reach) based on the count and size of the geofences on those Places
  3. Repeat Steps 1 and 2 until the impression capacity is satisfactory
  4. Add a ‘Targeting Code’ to each geofence. Each Proximity Design can hold multiple Proximity Sets, where a Set is made up of at least one geofence. The Targeting Code is used to specify the Proximity Set within the Proximity Design to use for ad targeting later.
  • The Planner can also request a ‘Payload’ for each Proximity Set: the payload is usually the name, type and location of the business, but can be anything (these attributes are employed in Step 8)
  1. On its cluster, Foursquare creates a highly optimized, binary Filter File containing all of the geofences and their payloads. Each Filter File represents a Proximity Set.
  2. The Filter File is uploaded to your instance of On-Prem. Upload time is a function of Filter File size and bandwidth, but the time is usually under 24 hours
  3. Queries to that instance of On-Prem are immediately validated against the new filter and any current filters
  4. When a coordinate satisfies a filter, the payload and Targeting Code are returned in the response packet as JSON. Proximity is designed for low-latency, high-volume queries real-time: the steps in orange in the above diagram are real-time and usually take about a millisecond, while the steps in yellow are asynchronous, but usually complete within a few hours.

Building Proximity Sets From Your Data or Third-Party Data

Most Proximity Sets are built from Foursquare data, but there may be instances where you would like Foursquare to create filters from your own data. This is not a problem — we can provide specifications for a Proximity Exchange Format that will allow us to build filters on your data or third-party data.

Implementing Proximity Sets

Proximity Sets are created on Foursquare's cluster and synced automatically with your Proximity implementation. Set creation can take up to 48 hours depending on the complexity of the filter geometry, but usually takes much less. On-Prem requires access to the Internet to synchronize Proximity Sets.

The Proximity service does not need to be restarted when new filters are added. If enough memory has been allocated (either via the maxMemory parameter in the Java client, or the -Xmx command line parameter for the On-Prem Server), the new configuration will be automatically loaded.

On-Prem instances will cache the Proximity Sets on disk, and only download filters that weren’t previously used.


Clickable Demo: Global Airports

Try out a sample Proximity Set online. This Proximity Set contains 3,367 polygons around airport complexes — most, but not all, around the globe. Clickable examples:


Demo Query Syntax

Input

The endpoint is found at https://geopulse.factual.com/geopulse/proximity/example/indices.
Insert the coordinates you wish to check into the designated parts of the URL below in your web browser. This example shows the URL for a coordinate within San Francisco International Airport.

623

Example:

curl "https://geopulse.factual.com/geopulse/proximity/example/indices?latitude=37.614740&longitude=-122.388995"

Output

If the coordinates fall into one of the geofences, the output will resemble the format below:

[
	{
		"index": "airports",
		"group": "AIRPORT-POLYS",
		"payload": {
			"factual_id": "54c2da95-3afb-4815-9710-dc2998ddab3e",
			"name": "San Francisco International Airport (SFO)"
		}
	}
]

If the coordinates do not fall into one of the geofences, an empty array will be returned:

[ ]

Precision and Accuracy Checking

Because Proximity is intended for precise point-in-polygon validation, input longitude and latitudes are checked for both precision and accuracy.

Inputs with fewer than four decimal places (~10m precision) return an ‘invalid location: IMPRECISE’;


Proximity Summary

  • Creates geofences from Foursquare's Global Places data, or from third-parties
  • Accommodates multiple point-and-radius and polygon geofences
  • Supports thousands of geofences per Proximity Set; supports multiple Proximity Sets
  • Server-side, high volume, high throughput geofencing solution
  • Sub-millisecond response time, ~20k qps on a quad-core server
  • HTTP Server
  • Operates internationally