Geofences

Contents

Introduction

Geofences represent custom regions or places monitored in your project. Depending on your use case, a geofence might represent a retail store, a neighborhood, a delivery, and so on.

Radar geofencing is more powerful than native iOS or Android geofencing, with cross-platform support for unlimited geofences, polygon geofences, and stop detection.

Create geofences to receive the following events:

  • user.entered_geofence
  • user.exited_geofence

Alternatively, if you don't have your own custom place data, Radar can tell you when a user visits a place, chain, or category, even if you haven't set up a geofence for that place. Learn more about Places.

Quickstart

Want to get started quickly? Follow these three steps:

  1. Start tracking. Integrate the SDK to start tracking users. Or, test with our toolkit apps for iOS or Android.
  2. Add context. Create geofences via the dashboard, CSV import, or the API.
  3. Handle events. Handle geofence events client-side or server-side via webhooks or integrations.

How it works

Geofencing works in the foreground and in the background. In the background, the SDK wakes up and sends locations to Radar every few minutes when the user moves more than 100 meters, and when the user comes to a stop for more than a few minutes. For most users, background tracking uses less than 2% battery per day.

All geofencing and event generation happens server-side. This allows Radar geofencing to be more powerful than native iOS or Android geofencing, with cross-platform support for unlimited geofences, polygon geofences, and stop detection.

Create geofences

You can create geofences via the dashboard, CSV import, or the API. You can create geofences in the Test environment for development and testing, and in the Live environment for production.

You specify the metadata for geofences when you create them, including the tag (an optional group for the geofence, e.g., store), external ID (an optional external ID for the geofence that maps to your internal database, e.g., 123), and description (a display name for the geofence, e.g., Store #123).

Geofences can be uniquely referenced by their Radar ID, assigned by Radar when a geofence is created, or by tag and external ID, assigned by you when a geofence is created.

Size and reliability

For maximum reliability, create geofences with a radius of 100 meters or greater. While you can create geofences with a radius between 50 and 100 meters, events may not be generated, or may be generated only after the user stops for a few minutes.

Accuracy and reliability may be further reduced if wi-fi is turned off, especially indoors, or if wi-fi is unavailable, such as in sparse suburban or rural areas. In general, these restrictions apply to all apps and SDKs using location services on iOS and Android, not just Radar.

Dashboard

To create a geofence via the dashboard, go to the Geofences page and click the New button. Search for an address or place, then enter a description, optional tag, optional external ID, and radius. Click Preview to preview the geofence, then click Create to create it.

CSV import

To create geofences via CSV import, go to the Geofences page and click the Import button. Then, select a CSV to upload.

The CSV must have 8 columns, with titles for the columns omitted.

  • description: A display name for the geofence. (optional)
  • tag: A group for the geofence. (optional)
  • externalId: An external ID for the geofence that maps to your internal database. (optional)
  • type: The type of geofence geometry, either polygon or circle. (required)
  • radius: The radius of the circle in meters for type circle, a number between 50 and 10000. (required for type circle, ignored for type polygon)
  • coordinates: A JSON string representing a center in the format [longitude,latitude] for type circle. A JSON string representing a closed ring of between 4 and 256 coordinates in the format [[longitude0, latitude0],[longitude1,latitude1],[longitude2,latitude2],...,[longitude0,latitude0]] for type polygon. Note that longitude comes before latitude, a GeoJSON convention. (required)
  • enabled: If true, the geofence will generate events. If false, the geofence will not generate events. (optional)
  • metadata: A set of custom key-value pairs for the geofence. A JSON string representing a dictionary with up to 16 keys and values of type string, boolean, or number. (optional)

If a geofence with the specified tag and external ID already exists, it will be updated. If not, it will be created.

For example, to import a circle geofence representing a café and a polygon geofence representing a neighborhood, you could use the following CSV:

"Monk's Café",venue,2,circle,50,"[-73.975363,40.783826]",true,"{""category"":""restaurant""}"
"SoHo",neighborhood,3,polygon,,"[[-73.996973,40.725660],[-73.998282,40.726294],[-74.001072,40.727660],[-74.002853,40.728603],[-74.003282,40.727936],[-74.003840,40.726310],[-74.004226,40.725351],[-74.004998,40.723530],[-74.005191,40.722993],[-74.005556,40.722115],[-74.004462,40.721334],[-74.001908,40.719496],[-73.999827,40.718016],[-73.997467,40.720863],[-73.997016,40.722212],[-73.996501,40.723497],[-73.995750,40.724278],[-73.995128,40.725107],[-73.996973,40.725660]]",true,

Again, note that longitude comes before latitude, a GeoJSON convention.

API

Finally, you can create geofences programmatically via the API. You can create a geofence via POST /api/v1/geofences, or upsert a geofence based on tag and external ID via PUT /api/v1/geofences/:tag/:externalId.

For example, to upsert a delivery geofence via the API:

curl https://api.radar.io/v1/geofences/delivery/123
    -H "Authorization: org_live_sk_8ca5fdbe82ab7d49a1ca5c3f"
    -X PUT
    -d "description=Delivery #123"
    -d "type=circle"
    -d "coordinates=[-74.001062,40.725934]"
    -d "radius=100"

Note that longitude comes before latitude, a GeoJSON convention.

Confidence

All geofence events have confidence levels. Confidence levels range from 1 (low) to 3 (high).

When geofences do not overlap, confidence will always be high. When geofences do overlap, confidence will be medium or low for geofences with a radius of 200 meters or less, depending on the user's location, the user's location accuracy, and the geometry of the geofence.

Stop detection

When Geofence Stop Detection is on, Radar will understand the difference between a user walking or driving through a geofence and stopping in a geofence, and will only generate an entry event when a user stops in a geofence. Turn on Geofence Stop Detection globally on the Settings page, under Geofences.

Support

Have questions after reading the documentation? We're here to help! Click the button on the bottom right of any page to chat with us, or email us at [email protected].