Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    


What is the dwell time after which Engine considers the device to be at a particular POI?

The SDK typically registers an "at" visit after a user has lingered at a single location for ~5 minutes. This brief time lag is used to ensure a high degree of confidence that the user isn't simply walking or driving by.

How does engine tell the difference between driving by, going into the store, or walking by the store?

Aside from examining dwell time (as noted above), when assessing location visits, the SDK accesses the accelerometer to perform activity detection around the time of the visit and may use the detected activity to inform the likelihood of being at the particular category of place the user is at.

What’s the difference between at and near a place, as Engine detects them?

The SDK uses a machine learning algorithm to determine the probability that you are actually at a particular venue that is trained against other users claiming to be at that venue, or similar venues. The at condition of an Engine Circumstance requires that Engine is confident that the user is actually there.

The near condition of a Circumstance specifies venues within approximately 150m of the current device location.

How is Engine more accurate than geofencing method? What about Polygons?

Geofencing is susceptible to a number of problems:

  • Streams of lat/lng signals from devices are often noisy and inaccurate. Despite having 6 decimals of precision, it's common for sequentially sampled geopoints at the exact same point to be off by 10s or 100s of meters.

  • Geofences themselves have to be accurate. Often times, the boundaries of places are either spatially or temporally porous (think Farmer's markets, food courts, etc.). Also personal definitions of boundaries aren't always clear. Have you ever been running late to meet someone and let them know you "were there", even though you were still barreling into the parking lot?

  • Geofences are generally two dimensional. The world is not.

Engine uses a machine learning model to assess the probability that you are in each place around you. Just a few of the features considered:

  • Popularity of places

  • Business operating hours

  • Lay of the land (relationship to street, building, and plot polygons)

  • Density of businesses in the surrounding area

  • Accelerometer motion

How is Engine different than beacons?

Beacons are hardware transmitters that broadcast across very short distances. Devices that come in contact beacons can be tied to very accurate locations (provided that the hardware's location is known, and hasn't been inadvertently changed by someone unknowingly moving it). As a hardware solution, beacons only work where the actual hardware is deployed. Beacons can be expensive to deploy and maintain, and will not enable you to track devices across places like your competitors' stores or any other real estate you don't own. Engine, on the other hand, relies on machine learning models examining all available signals to the device and thus can work cheaply just about everywhere.

How large is the Engine SDK?

Engine adds approximately 1.5 megabytes to the download size of your app, depending on the architecture (see below)

Platform Architecture Download Size
Android x86 1.4 MB
Android arm64-v8a 1.2 MB
Android armeabi-v7a 1.3 MB
iOS arm64 1.34 MB
iOS armv7 1.67 MB

What’s the average battery consumption?

Engine should not exhibit more than ~1% difference in overall power consumption.

How do Engine API keys work?

Your Engine API key identifies your app to Factual. There are not unique
keys per user or any kind of token dance required. You can get your API key
from the Engine web UI under your profile.

What location permissions does Engine require?

In iOS, Engine requires either the authorizedWhenInUse or authorizedAlways authorizations. Obviously, Engine will only be able to perform background Circumstance detection if authorizedAlways is available.

In Android, Engine requires the _ACCESS_FINELOCATION and INTERNET permissions.

How does Engine access Factual Global Places data?

Engine keeps a small cache of Factual Global Places data onboard, in order to
service Circumstance checks without constantly making network connections back to
Factual. When user Circumstances are evaluated against places, it is against
the local cache.

How do push configurations in Engine work?

Any configuration you make in the Engine web UI is committed when you click the push changes
button. Periodically, individual instances of your app will
call back to Factual to see if there are any configuration updates. Having pushed your changes, these apps will be notified that there is an update and that they should pull it immediately.

How often are Engine configurations updated?

Instances of Engine in the field are configured to call back to Factual when your app is started, provided that it has been at least 24 hours since the last time the app started. This call simply checks to see if any configuration changes need to be pushed. It's possible individual devices may not receive the latest update within 24 hours, but generally, most of your active devices should be updated within that period.

Updated 2 months ago


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.