Observation Graph SDK for Android

The steps below will guide you through installing the Observation Graph SDK into your app via Android Studio and Java.


  • The Observation Graph SDK is compatible with API level 20 or higher.
  • After compilation, the SDK should add approximately 1.5 MB to your app’s size.
  • The SDK requires ACCESS_FINE_LOCATION and INTERNET permissions.

Get an API key and SDK Download

Your Factual account representative will provide you with an API key and a download of the SDK.

Copy the AAR to Your Project

Copy the AAR to your preferred location for libraries. E.g., app/libs.

Add Repositories and Dependencies

Add Maven and the path to the AAR as repositories in your app/build.gradle as follows:

repositories {
    // Volley and Thrift are found here.

    flatDir {
        // Path to the AAR, relative to your project's "app" dir.
        dirs "libs"

dependencies {

Add the AAR and dependencies to app/build.gradle as follows:

dependencies {
    // Existing dependencies

    // Third party libraries used by the SDK:
    implementation 'com.android.volley:volley:1.1.0'
    implementation('com.google.android.gms:play-services-location:11.0.4', {
        exclude group: 'com.android.support', module: 'support-v4'
    implementation 'org.apache.thrift:libthrift:0.9.3'
    implementation 'com.google.android.gms:play-services-analytics:11.0.4'

    // The Observation Graph AAR:
    implementation(name: 'factual-og-sdk-android', ext: 'aar')

You may need to exclude META-INF/DEPENDENCIES by adding a packagingOptions block under android in your app/build.gradle as follows:

android {
  packagingOptions {

If you would like notifications from the SDK in the app’s background state we recommend implementing the SDK via a Broadcast Receiver. Please reference the code examples at https://github.com/Factual/engine-examples

Location Permissions

Your AndroidManifest.xml should include the following permissions and feature:

    <service android:name="com.factual.observationgraph.FactualObservationGraph"/>
    <receiver android:name="com.factual.observationgraph.FactualClientReceiver"/>

  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-feature android:name="android.hardware.location.gps" />
  <uses-feature android:name="android.hardware.location.network" />

The SDK does NOT prompt for these permissions on its own. We’ve deliberately left that to you, so that you can lump in any other permissions you may require, as well as choose the method and timing of the prompt as you require.

Sample Implementation Code

Following is an example Android Activity running the Observation Graph SDK.

A few things to note:

  • The package name in the example would be replaced by your own.
  • The SDK detects which location permissions your app has requested and behaves appropriately. It will not request any location authorizations on its own. For illustrative purposes, the code example below shows you how this can be accomplished.
  • The FactualClientListener interface provides debugging info to your app.

Insert your API Key

In the code example above, you’ll need to provide your API key:

FactualObservationGraph.initialize(this, "your API Key Goes Here");