Factual Geopulse Proximity Overview

Geopulse 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 qps on a standard, four core server.


Run 20,000 QPS on a standard four core server

Geopulse 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 Factual’s 90 million+ businesses in over 50 countries. Multiple geofences are compiled into a single Geopulse Proximity Proximity Set; each filter can contain up to 750,000 geofences each.

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

How It Works

The process is asynchronous and straightforward:

  1. Install Geopulse On-Prem on your infrastructure.
  2. Create geofences based point-radius or polygons with our Geopulse Proximity Designer built on Factual’s Global Places Data, which supports geofencing by business name, category, or merchant chains. Alternatively, use your own shape files or spatial data. We convert the geofences to an optimised 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 Geopulse On-Prem.
  5. The service returns a JSON data packet describing what Proximity Sets the input coordinate pair satisfies.
Geofence Creation

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


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

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

Proximity Set Generation

The power of Geopulse 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 re-started 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 Factual

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

Factual Creates Proximity Sets

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

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

Run On Your Infrastructure, On-Premises

Geopulse Proximity runs on your infrastructure within a container called Geopulse 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 Factual Place data, and implement those filters locally as soon as possible thereafter. It looks something like this:

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

  1. Media Planner queries Factual Places data by name, chain, or business category, and assigns a geofence radius in meters via the Geopulse 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)
  5. On its cluster, Factual creates a highly optimized, binary Filter File containing all of the geofences and their payloads. Each Filter File represents a Proximity Set.
  6. The Filter File is uploaded to your instance of Geopulse On-Prem. Upload time is a function of Filter File size and bandwidth, but the time is usually under 24 hours
  7. Queries to that instance of Geopulse On-Prem are immediately validated against the new filter and any current filters
  8. When a coordinate satisfies a filter, the payload and Targeting Code are returned in the response packet as JSON.

Geopulse 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 Factual data, but there may be instances where you would like Factual 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 Geopulse Proximity Sets

Proximity Sets are created on Factual’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. Geopulse On-Prem requires access to the Internet to synchronize Proximity Sets.

The Proximity service does not need to be re-started 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:

(The JSON response packet returned from the links above is designed for machine consumption and will look unsightly in the browser; use an extension like JSONView for Chrome or Firefox to render the results more readable.)

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.

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 Geopulse 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’;

Geopulse Proximity Summary