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    

Technical Specs

Tracking Permissions

Engine relies on the user to grant access to location services via iOS (in app or always). Engine will NOT seek to determine a user’s location through alternative methods (for example, IP lookup or SSID lookups) if the user has not granted location permissions. Engine does NOT explicitly ask for any location permissions, but rather detects what permissions have been granted to your app and behaves accordingly. If you want Engine to monitor for Circumstances in the background, it is the responsibility of your app to request the necessary location authorizations.

SDK Size

We measure the Engine SDK in terms of how much larger it would make your final shipping app, rather than the size of the binary files we deliver to you (pre-compilation). A basic Engine installation should add ~1.5 MB to the size of your app. Keep in mind that this isn’t a cut and dry calculation, as you may be adding additional code to your app to actually implement the cool things that Engine now enables you to do.

Network Resources

In order to function, Engine requires two types of resources periodically: the latest configuration file, which configures Engine to your specific requirements; and map tiles, containing geographic data required for place attachment.

Configuration files

Engine checks daily (however, only when a user opens your app) for the latest configuration file. Configuration files contain things like the latest location and versions of map tiles and Circumstance definitions. The request for a configuration file transmits the following:

Phone make

Phone model

Operating system


Carrier Country

Operating system version

Engine version

Device Id(1)

Configuration id

(1)Depending on configuration and terms, this may be a random Id generated at install, the IDFA, or a completely random string. It is used to track unique configuration requests in broad numbers, e.g., MAUs.

Map tiles

Engine keeps a cache of geographic data such as nearby businesses, street polygons, etc. This cache is served in “tiles”- roughly square segments of the earth around the user. Any time a user enters an area for which Engine hasn’t cached any data, a new tile is requested. The following data is sent when requesting a tile:

  • Level 7 Geohash of the tiles being requested.
  • Average tile size is ~3kb. Range is between 0kb and 10kb.

Technical Specs

Suggested Edits are limited on API Reference Pages

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