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    

Android Observation Graph SDK

Getting Started

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


Please reference the Javadoc for more detailed class information

Sample Code

For further examples please reference the code at https://github.com/Factual/sdk-examples

1. Ensure the SDK requirements are met

  • The SDK is compatible with API level 21 or higher.
  • After compilation, the SDK should add under 1.0 MB to your app's size.
  • The SDK requires ACCESS_FINE_LOCATION and INTERNET permissions.

2. Get an API key and SDK Download

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

3. Copy the AAR to Your Project

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

4. 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:
    /* Play Services for Location */
    implementation 'com.google.android.gms:play-services-location:12.0.1'

    /* Volley for HTTP requests */
    implementation 'com.android.volley:volley:1.1.0'

    implementation 'org.apache.thrift:libthrift:0.9.3'

    /* Room for data persistence */
    implementation 'android.arch.persistence.room:runtime:1.0.0'

    // The OG 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 {

5. Update Location Permissions

Your AndroidManifest.xml should include the following:


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

Receiver and Service:

    <receiver android:name="com.factual.android.LocationUpdateReceiver"/>
      android:label="Observation Graph Job Service"

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.

6. Follow the sample implementation

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.
package com.factual.observationgraphandroid;

import android.Manifest;
import android.content.pm.PackageManager;
import android.os.Bundle;
import android.support.v4.app.ActivityCompat;
import android.support.v4.content.ContextCompat;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;

import com.factual.android.FactualException;
import com.factual.android.ObservationGraph;

public class MainActivity extends AppCompatActivity {
  public static final String LOGTAG = MainActivity.class.getName();
  public static final int PERMISSIONS_REQUEST_CODE = 100;
  public static final String API_KEY = "your-api-key";

  protected void onCreate(Bundle savedInstanceState) {

  public void startOG() {
    if(isRequiredPermissionAvailable()) {
      try {
        ObservationGraph.getInstance(this, API_KEY);
      } catch (FactualException e) {
        Log.e(LOGTAG, "Factual Exception: " + e);
    } else {

  public boolean isRequiredPermissionAvailable() {
    return ContextCompat.checkSelfPermission(this,
        Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED &&
            Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED &&
            Manifest.permission.INTERNET) == PackageManager.PERMISSION_GRANTED;

  public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
    if (requestCode == PERMISSIONS_REQUEST_CODE) {
      if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
        Log.d(LOGTAG,"permissions granted");
      } else {
        Log.e(LOGTAG,"permission denied");

  public void requestLocationPermissions() {
        new String[]{

Insert your API Key

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

public static final String API_KEY = "your-api-key";

Android Observation Graph SDK

Suggested Edits are limited on API Reference Pages

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