Frequently Asked Questions


Engine Location Detection

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

Engine typically registers an “at” visit after a user has lingered at a single location for ~2 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, Engine 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?

Engine 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 200m 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

Using a machine learning model, Engine can correctly identify that you are inside a particular place, even if your lat/lng in relation to the place polygon says otherwise.


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.


Size and Data Consumption

How large is the Engine SDK?

Engine adds approximately 1.5 mb to the download size of your app, depending on the architecture.

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


What’s the average battery consumption?

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


Engine Access and Configuration

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 Garage.


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_FINE_LOCATION 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 Garage 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.


I see a log message “The SDK was unable to get a location fix from the device” while using the Android emulator.

This message may occur if the emulator is not using the latest version Google Play Services. To fix, update Google Play Services in the emulator as if you were using a real device, i.e. log in to the Play Store and update Google Play Services. You can check the Play Services version in the Settings > Apps > Google Play services menu. After updating, restart the app on the emulator and you should see “Location Update occurred at…” in the logs at startup.


I updated Google Play services but I’m still seeing “The SDK was unable to get a location fix from the device” in the emulator log.

This may mean that the emulator is not configured with an initial location (this can happen if you you’re using a virtual device for the first time, or if you wipe the data of an existing virtual device.) Set a location manually in the extended controls of the emulator and tap the “Send” button. If you’re testing the sample code, restart the app to see the effect.


Why would the SDK return the info message: “Telemetry not logged because there was a lack of permission?

Telemetry will not be logged if the user has not accepted the appropriate location permissions or if the device has “Ad Tracking” disabled.


V3 Factual APIs

Can I use my V3 API key with Engine?

No. Engine requires a separate Engine API key. To receive an Engine API key, sign up here: here.


What happened to previous (“V3”) Factual APIs?

We are in the process of sunsetting Factual’s V3 APIs. Read more about the V3 API sunset in our developer documentation.


Can I accomplish the same things with Engine as the V3 APIs?

Not yet. We are in the process of porting existing search features to Engine.