Geopulse API Documentation

The Geopulse APIs are a suite of APIs that allow Factual partners integrated with Geopulse to perfom a number of different functions, depending on the needed use case. The Geopulse APIs can be used for use cases as simple as calculating avails using your own sample data against a specific design to powering a fully functional embeddable Factual UI.

A few examples for what these APIs enable:

  • Manage memory usage in Geopulse On-Prem software
  • Drive a dropdown of available targeting in a partner UI
  • Estimate reach for a given Proximity or Audience design
  • Embed the Factual designer UIs into your own platform
  • Managing complex permissions to Geopulse designs

Authentication

In V4, server API calls are made by passing your API key into the KEY (case-sensitive) parameter, and making your requests through https:

https://api.factual.com/categories?KEY=your_API_key

Instead of cryptographically signing your requests to verify that requests are being made by your service, as is required by our V3 API, you restrict IP addresses that are authorized to make API calls using your key (server-side), or restrict access by Bundle Id (iOS).

If you do not bind your key to an IP address or Bundle Id, you may be responsible for any unauthorized access to your API key.




image: API key manager, accessible from your profile when you are logged into www.factual.com.


We’re still working on support for Android and client-side (Javascript/browser) access, so currently V4 APIs are unavailable to those platforms.

Tracking Throttle Allocation (Real-time)

Every API response includes the remaining throttle allocation for the specified API key in the X-Factual-Throttle-Allocation HTTP header.

Example:

X-Factual-Throttle-Allocation:{"burst":"0%","daily":"0%"}

Notes:

  • The Factual API has a requests per minute limit as well as a per day limit. Exceeding the requests per minute will result in a short delay in processing each request rather than denying requests. The delay will, in aggregate, result in your request volume to be no greater than the RPM limit.
  • Exceeding the RMD will result in a 429 response.
  • RPD and RPM are calculated by per individual request method.
  • RPD and RPM are calculated based on rolling 24 hour and 1 minute periods.

Tokens

Introduction

This document details generating access tokens that can be used by your web clients to make secure, direct calls to Factual’s APIs. Using tokens enables you to avoid proxying API calls through your own servers and is a required piece of implementing an embeddable UI workflow.

Requirements

The basic requirements to implement tokens to access Factual are:

  • A server in your control that can authenticate your clients against your own user DB
  • A Factual API key
  • The ability for your server to make an outbound API call to Factual
  • The ability for your server to forward the results of an API call from Factual to your clients


The diagram below details the basic authentication flow:


As shown in the diagram above, the basic steps are:

  1. Your user attempts to login from one of your clients by sending login credentials to your server.
  2. Assuming the user has acceptable credentials, your server will either:
    • Return the most recent Factual authentication token it has for the user (assuming that it hasn’t passed its expiration date).1
    • Request a new token from Factual on behalf of that user.2
  3. In the event a token was requested, Factual will return the token to your server.
  4. Your server in turn will return the access token to the client.
  5. Your client will use the token to make a request to Factual.
  6. Factual will determine if the token is valid, and what permissions it should have.
  7. As appropriate, Factual will return data to the client.

Note: Until your client’s Factual token has expired, your client does not need to re-request tokens to make calls to Factual.


1 There is no harm in asking for a token redundantly. Factual will consistently return the same token is for that user.

2 If this is the first time the user has requested access to Factual, all necessary configuration on Factual’s side will be performed immediately, in order to respond to your server’s request in a timely manner. E.g., each user’s Factual credentials are generated quickly but lazily.


Getting an API Key

If you haven’t already, you can register an account at Factual here. Once you’ve done that (or logged into Factual), go to the Factual API key manager at https://www.factual.com/keys.

  1. Within the key manager, you’ll be generating a Server App key:
  2. After you generate your Server App key, hit modify.
  3. Click the Security and Permissions tab.
  4. Enter the IP address of your server. This helps prevent use of your API key to generate tokens from unauthorized domains, if it were to be compromised.
  5. Hit save.
  6. Your API key is listed as OAuth Key. For this use case, you will not require the OAuth Secret.

Getting Tokens

Tokens are generated using an https request to Factual’s V4 API. Authentication of your token API call is performed simply by supplying your API key to the KEY parameter (all CAPS) to the /token/user endpoint. Along with your API key, the following parameters are required (unless you provide a user Id, as detailed later):

  • email (User email address.)
  • first_name (first name of user. must not be blank or all white space.)
  • last_name (last name of user. must not be blank or all white space.)


Token API request

The basic syntax for getting a token is to make a GET request as follows:

https://api.factual.com/token/user?email=email_address&first_name=first_name&last_name=last_name&KEY=api_key

  • As per any http GET request parameter, the email address and first/last names must be URL-encoded.
  • The request must be transmitted securely through https.


Refresh Token API request

Once you have received a successful token response containing a user id, you should request future tokens for that user simply using the user id:

https://api.factual.com/token/user/user_id?KEY=api_key


Token API response

Responses to the Factual API contain a JSON object in the response body, in addition to metadata in the http headers and the http status code. The standard http response body will contain data conforming to the JSend convention, augmented with a few other attributes:

  • status (success, fail, error)
  • data (for success_/_fail)
  • message (for error)
  • version (API version)


Standard response

An http 200 response will be accompanied with JSON, similar to the following, containing the user’s userId, token and the expiration date of the token:

{
  "version":4,
  "status":"success",
  "data":{
    "uid":"fbd96e3a-1d7d-4a93-b201-020e53e65417",
    "token":"XTH4sYzIjP5cG6RzqSoi",
    "expiration":1443650290
  }
}

You should forward both the token and expiration date to your clients. The expiration date will be in epoch time, in seconds.


Exceptional paths
http response code message explanation
400 unknown parameter ‘parameter_name’ You have entered a parameter that the API does not recognize.
400 parameter ‘parameter_name’ should not be used alongside a user id. You have provided both a user id (in the URL) as well as user identifying information such as email, first_name, or last_name. You should only be providing the user Id if you have it.
400 missing required parameter ‘parameter_name’ You have not provided a user id and any of the email, first_name or last_name parameters is either missing or blank.
400 invalid email address The email address you provided is invalid.
401 invalid API key Your API key is not valid. This is most likely because you’ve either regenerated your API key (invalidating the existing one), or because you’ve made a copy/paste mistake.
403 throttled You’ve made too many API calls over the allotted period of time.
404 resource not found There is a typo somewhere in the request URL.
404 user not found The user id provided in the URL is invalid.

Using Tokens

Once your client has a token and expiration date, it can make API requests directly to Factual. In order to make requests to Factual:

  1. Ensure that the expiration date for the token has not passed. If it has, your client-side code should be prepared to ask your server for a new token, which it will have to fetch from Factual.
  2. Insert the valid token into the Authorization header as an OAuth 2.0 Bearer token.

For example, if the token is XTH4sYzIjP5cG6RzqSoi, the header would look like:

GET /geopulse/designs/ HTTP/1.1
Host: api.factual.com
Authorization: Bearer XTH4sYzIjP5cG6RzqSoi

Refreshing Tokens

If the token has expired, your server simply needs to make a new request to the token API with the appropriate user id. Factual will return a new token.

Management

Introduction

The Geopulse Management APIs are a suite of APIs that enable you to manage the building and deployment of Geopulse Proximity and Audience designs.


Lifecycle

The basic lifecycle of a Proximity/Audience design is as follows:

  1. A user creates and saves a design using Factual’s authoring tools. At this point, a design id is generated.
  2. The user requests that the design be built. At this point, a build id is generated.
  3. Factual processes the build request.
    • Using information contained in the Proximity or Audience design, Factual generates a targeting file, known as a Proximity Filter or Audience Set, respectively.
    • These targeting files are used in conjunction with Factual’s Geopulse On-Prem software to provide real time targeting information.
  4. Once the build is successfully processed, the design is now associated with an available build.
  5. The user requests a deployment of that build to a given partner’s On-Prem software. At this point, a deployment id is generated.
  6. An administrator of the On-Prem software approves the deployment request and activates the deployment.
  7. Upon activation, the targeting file associated with the deployment will get loaded into memory in the partner’s On-Prem software and responses from the targeting file will begin to be returned.
  8. When the campaign is complete, the administrator can deactivate or delete the deployment, removing the targeting file from their On-Prem software.

A few non-standard paths exist:

  • After step 5 and before an administrator has completed step 6, the user that requested deployment of a built design may cancel their pending request.
  • At step 6, the administrator may reject the activation request (e.g. if the targeting file associated with the deployment is abnormally large).
  • At step 7, the administrator may tag a deployment for the purpose of optimizing server capacity.
  • At step 7, the administrator may temporarily deactivate a build to free up memory in their On-Prem servers and then reactivate it when convenient.

API Overview

The following APIs enable programmatic access to each step of the aforementioned lifecycle:

Endpoint Description
/geopulse/designs/design id Get meta-data for a specific design
/geopulse/designs/ List all designs visible to you
/geopulse/designs/design id/request Request that a design be built by Factual
/geopulse/builds List designs that have been successfully built, build history, and deployment status
/geopulse/builds/build id/request Request that a built design be activated
/geopulse/deployments/ List deployments
/geopulse/deployments/deployment id/cancel Cancel an activation request before it is approved and activated
/geopulse/deployments/deployment id/reject Reject a request to activate a build
/geopulse/deployments/deployment id/activate Activate a build
/geopulse/deployments/deployment id/deactivate Deactivate a build
/geopulse/deployments/deployment id/delete Delete a build
/geopulse/deployments/deployment id/tag?tags=tags Tag a deployed build (for capacity management)

Below, you will find comprehensive documentation on each API call.

Get Design

Returns all details about a specific Proximity or Audience design.

Endpoint
https://api.factual.com/geopulse/designs/(design Id)
  • This endpoint only accepts GET requests.
  • Replace (design Id) with the id of the design for which you are requesting information.
Example
https://api.factual.com/geopulse/designs/24e12f0e-ab5f-47e0-8b7d-a7ce63241068?KEY=your_api_key
Request Parameters
Parameter name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response Number
4
status The status of the API response String
“OK”
response The response object JSON object
response.data The data object, containing a single design object with the parameters found in the below “Response Data Parameters” JSON object
Response Data Parameters

Parameters within the response.data object described above:

Parameter name Description Datatype Example
id The design ID String (GUID)
“38697e15-9e9e-4917-b55b-6431b99392f4”
name The design name String
“LA Car Dealerships”
type proximity or audience String (enumerated)
“proximity”
status in_design, requested, rejected, building, failed, built String (enumerated)
“in_design”
created_at Timestamp for when design was created String (date)
“2016-01-06T17:11:17.000Z”
updated_at Timestamp of most recent design update String (date)
“2016-01-06T17:11:17.000Z”
external_build Whether or not the design is associated with a build created outside of the Geopulse designer tools. A design with a value of “true” cannot be edited. Boolean
false
design_size (Deprecated) An internal value that estimates how complex this design may be to build on a relative scale. Not intended to be user facing. Number
12
most_recent_build The build ID of the most recent build String (GUID)
“ac5925c7-e727-45b5-848b-c2532dc84db7”
owner_id The user id of the design’s owner String (GUID)
“eea9f6ef-c9f3-430a-8db0-d89e8476aebd”
owner_org_id The id of the design owner’s organization String (GUID)
“d4e49049-07fd-4c67-8325-1c803a8d1857”
owner_name The email of the design owner String
“user1@factual.com”
price_cpm Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. JSON Object
{"base": “0.75”}
active_builds The number of builds associated with this design that have been deployed to a partner’s On-Prem software Number
1
is_shared_to_current_user Whether access to the design has been explicitly shared with the current user Boolean
false
is_shared_to_current_org Whether access to the design has been shared with the current user’s entire organization Boolean
false
sets An array of sets contained within the design object JSON Array
sets[row].set_id The id of the set String (GUID)
“d151ea2c-9879-460c-a169-77a0de9ec3c5”
sets[row].set_name The name of the set String
“Used Car Dealers”
sets[row].targeting_code The targeting code associated with the set String
“cars_1000m”
set_ids An array of all set IDs associated with the design JSON Array
collaborators An array of all users or orgs explicitly granted access to the design JSON Array
collaborators[row].type user or org String
“user”
collaborators[row].id The user or org ID of the collaborator String (GUID)
“eea9f6ef-c9f3-430a-8db0-d89e8476aebd”
collaborators[row].label The human readable representation of the user or org. Email for user. Org Name for org. String
“user1@factual.com”
collaborators[row].permissions Permissions defining the collaborator’s level of access to the design JSON Object
collaborators[row].permissions[row].view Whether or not the collaborator has access to view the design Boolean
true
collaborators[row].permissions[row].edit Whether or not the collaborator has access to edit the design Boolean
true
Design Status Enumeration
Design Status Description Design Editable? Can Request Build?
in_design The design is in the design phase and has not been requested or built yet. Yes Yes
requested The user has requested a build get created from the design, and it is awaiting being places onto Factual’s cluster to process the build. The design is frozen in this state, and cannot be changed until the build successfully completes or the build request is rejected. No No
rejected The build request was rejected by Factual, and must be re-requested. The design is free to be edited in this state. Yes Yes
building The design is in Factual’s cluster queue to be processed into a build. No No
failed The build process failed, and Factual will either fix the build and re-try or reach out to make any necessary fixes. No No
built The design has been successfully built. Yes Yes


List Designs

Returns all details about any Proximity or Audience designs for which you have been granted visibility.

Endpoint
https://api.factual.com/geopulse/designs/
  • This endpoint only accepts GET requests.
Example
https://api.factual.com/geopulse/designs?type=proximity&KEY=your_api_key
Request Parameters
Parameter name Description Datatype Example
 limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number
limit=10
 offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number
offset=0
 owner The user ID of the user that created the design.(1) String (GUID)
owner=eea9f6ef-c9f3-430a-8db0-d89e8476aebd
 owner_org_id The organization ID of the user that owns the design. String (GUID)
owner_org_id=d4e49049-07fd-4c67-8325-1c803a8d1857
 q A full-text search string. String
q=car
 type The type of design. Either proximity or audience. String (enumerated)
type=audience
 visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings
visibility=coke
visibility=star_market,pepsi
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required

1 On rare occassions, a design may be administratively assigned ownership to a different user than the one who created it. For example, if a user was to leave an org.

Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”
response The response object JSON object
response.data The data object containing an array of individual design objects.

For a full description of all parameters available in each row of this data object, see Get Design: Response Data Parameters above.
JSON array
included_row_count The total rows included in the data array contained in this response Number
23
total_row_count The total rows available for this data array. See paging Number
1002


Request Build of a Design

Sends a request to Factual that this design be processed and a targeting file be produced from it. Requesting a build will put the design into status “requested” and render the design un-editable until the build is either completed or rejected by Factual. Note that a request build call is only valid for designs of status “in_design”, “rejected”, or “built”. For more information on design status, please see Get Design: Design Status Enumeration above.

Endpoint
https://api.factual.com/geopulse/designs/(design id)/request
  • This endpoint only accepts POST requests.
  • Replace (design id) with the id of the design you are requesting a build for.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/designs/7e805739-34c2-43d8-b19c-965b2a19b715/request HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 81

reason=require+asap&KEY=your_api_key
Request Parameters
Parameter name Description Datatype Example
*reason A text description of the reason for this build request String
reason=testing
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


List Builds

Returns a list of all designs that have been successfully built, along with the build history and current deployment status of each design.

Endpoint
https://api.factual.com/geopulse/builds
  • This endpoint only accepts GET requests.
Example
https://api.factual.com/geopulse/builds?type=audience&deployment_status=activated&KEY=your_api_key
Request Parameters
Parameter name Description Datatype Example
 limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number
limit=10
 offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number
offset=0
 q A full-text search string. String
q=car
 type The type of design. Either proximity or audience. String (enumerated)
type=audience
 visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings
visibility=coke
visibility=star_market,pepsi
 deployment_status The builds current deployment status: activated, deactivated, requested, requested_replacement, out_of_date, or undeployed.

For a full description of the various deployment statuses, see Deployment Status Filter Enumeration below.
Comma delimited array of strings
deployment_status=activated,deactivated
 deployment_target The slug of the target org to which the deployment_status parameter should be applied. Does nothing if deployment_status is not specified. Comma delimited array of strings
deployment_target=bigdsp
 min_size Minimum size of the targeting file associated with the most recent build Number
min_size=10000
 max_size Maximum size of the targeting file associated with the most recent build Number
max_size=10000000
 sort Sort by build_date, requested_at, or last_build_size String (enumerated)
sort=last_build_size
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”
response The response object JSON object
response.data An array of design objects and their associated metadata.

For a full description of all parameters available in each row of this data object, see Response Data Row Parameters below.
JSON array
included_row_count The total rows included in the data array contained in this response Number
23
total_row_count The total rows available for this data array. See paging Number
1002
Response Data Row Parameters
Parameter name Description Datatype Example
id The design ID String (GUID)
“38697e15-9e9e-4917-b55b-6431b99392f4”
type proximity or audience String (enumerated)
“proximity”
name The design name String
“LA Car Dealerships”
owner Email of the design owner String
“user1@factual.com”
builds Array of build objects associated with this design JSON Array
builds[row].id Build ID String (GUID)
“a4d51e3b-ae95-4917-a7db-878255f334ea”
builds[row].name Name of the build. This is equal to the design name at the point that the build is initially generated. String
“LA Automotive”
builds[row].status The processing status of the build. Currently will only return DONE String (enumerated)
DONE
builds[row].size Size, in bytes, of the targeting file associated with the completed build Number
1061822
builds[row].requested_at Timestamp representing when the build was initially requested String (date)
“2016-02-29T22:26:26.000Z”
builds[row].build_date Timestamp representing when the build was successfully completed String (date)
“2016-03-01T05:22:33.000Z”
builds[row].builder Email of the user who requested the build String
“user1@factual.com”
builds[row].source The inventory source (e.g. ad exchange) that was used to create the build object. Only returned for designs of type “audience” where an inventory source must be specified. String
“factual_dap”
builds[row].audience_index_version Date that the inventory source used to create the build was last processed String (date)
“2016-02-29T22:26:26.000Z”
builds[row].price_cpm Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. JSON Object
{"base": “0.75”}
deployments Array of deployment objects associated with this design JSON Array
deployments[row].id Deployment ID String (GUID)
“5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b”
deployments[row].target Name of the target where this deployment is associated String
“Big DSP
deployments[row].target_id ID of the target where this deployment is associated String (GUID)
“42dc6d44-a910-4e11-8fdb-8051c10aadee”
deployments[row].status Status of the deployment activated, deactivated, requested String (enumerated)
“activated”
deployments[row].build_id Build ID of the build object associated with this deployment String (GUID)
“a4d51e3b-ae95-4917-a7db-878255f334ea”
last_build_id Build ID for the most recent build of this design String (GUID)
“a4d51e3b-ae95-4917-a7db-878255f334ea”
last_build_name Name of the most recent build of this design String
“LA Automotive”
last_build_builder Email of the user who requested the most recent build of this design String
“user1@factual.com”
last_build_date Timestamp of when the most recent build of this design was completed String (date)
“2016-03-01T05:22:33.000Z”
last_build_source Inventory source of the most recent build of this design String
“factual_dap”
last_build_size Size in bytes of the targeting file associated with the most recent build of this design Number
110292
last_build_audience_index_version Date that the inventory source used to create the build was last processed String (date)
“2016-02-29T22:26:26.000Z”
Deployment Status Filter Enumeration
Deployment Status Filter Description
activated Return any designs with a deployment that is “activated” on the target partner’s system
deactivated Return any designs with a deployment that is temporarily “deactivated” the target partner’s system (e.g. to conserve memory on the partner’s servers)
requested Return any designs with a deployment that is “requested” on the target partner’s system, where that deployment has not been activated or rejected yet.
requested_replacement Return any designs that have a deployment that is “requested” which, if activated, will replace an existing deployment associated with that design. A design can only have a single build activated on a given partner’s system at any given time.
out_of_date Return any designs that have a deployment on the target partner’s system where the build associated with that deployment is out of date, and a more recent build has since been generated. (e.g. Design ABC has been built 5 times, but only build 4 is deployed to a partner)
undeployed Return any designs that have no deployment associated with the target partner’s system.

Request Deployment of a Built Design

Request that a build be deployed to a partner’s infrastructure. Note that this API represents a request to a Geopulse Administrator who must subsequently activate the request (or reject it). If a build already has an associated deployment on a given target org’s infrastructure, it cannot be requested to that org. For a single design, only one build may have an activated deployment on a given target org’s infrastructure at any time (e.g. if Design XYZ has 4 builds, a given target org can only have one of those builds deployed at any time.)

Geopulse Administrators can see pending requests by using the deployment list API.

Endpoint
https://api.factual.com/geopulse/builds/(build id)/request
  • This endpoint only accepts POST requests.
  • Replace (build Id) with the id of the build for which you are requesting activation.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/builds/03c26917-5d66-4de9-96bc-b13066173c65/request HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 104

message=this+is+for+a+geotargeting+campaign&targetId=fc873d35-6f59-4d41-822a-254b716d8532&KEY=your_api_key
Request Parameters
Parameter name Description Datatype Example
 message A message to send with the deployment request if you would like Factual to know additional metadata String
message=this+is+a+test
*targetId The ID of the deployment target that the user is wanting to deploy to String (GUID)
targetId=fc873d35-6f59-4d41-822a-254b716d8532
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Cancel a Deployment Request

Cancel a pending deployment request. This API is intended to support cancellation of a deployment request by the user who initiated the request. Only requests which have not already been either activated or rejected can be cancelled.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/cancel
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id that was returned by the request for the build to be activated.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/deployments/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/cancel HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67

message=apologies%2C+but+this+was+the+wrong+build&KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
 message A message to send with the deployment cancellation if you would like Factual to know additional metadata String
message=wrong+partner
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


List Deployments

The Deployment List API returns a list of all builds that have been deployed across your infrastructure, whether they are activated, deactivated, or requested. To return only a list of requested deployments, add the filter “status=requested” to this call. Similarly, to return only a list of activated deployments, add the filter “status=activated”

Endpoint
https://api.factual.com/geopulse/deployments
  • This endpoint only accepts GET requests.
Example
https://api.factual.com/geopulse/deployments?type=proximity&status=activated&KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
 limit When paging through longer lists of data, the maximum number of rows to return per request. See paging Number
limit=10
 offset When paging through longer lists, the offset from the first row of data to begin at. See paging Number
offset=0
 q A full-text search string. String
q=car
 type The type of design. Either proximity or audience. String (enumerated)
type=audience
 target_type The type of target the deployment is associated with (e.g. OnPrem, LIDS, etc.) String
target_type=onprem
 visibility Filter out designs that do not contain the granted visibility tags Comma delimited array of Strings
visibility=coke
visibility=star_market,pepsi
 status Status of the deployment: activated, deactivated, or requested

For a full description of the various deployment statuses, see Deployment Status Enumeration below.
Comma delimited array of strings
status=activated,deactivated
 min_size Minimum size of the targeting file associated with deployed build Number
min_size=10000
 max_size Maximum size of the targeting file associated with deployed build Number
max_size=10000000
 start_date Starting timestamp to filter deployments by time of approval. Integer (epoch date, seconds)
start_date=1475167405
 end_date Ending timestamp to filter deployments by time of approval. Integer (epoch date, seconds)
end_date=1475167424
 new_build Filter by the following: true=deployments associated with the first build of a design, false=deployments associated with a refreshed build Boolean
new_build=true
 sort Sort by updated_at, approved_at, build_date, or build_size String (enumerated)
sort=build_size
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”
response The response object JSON Object
response.data An array of deployment objects. JSON Array
included_row_count The total rows included in the data array contained in this response Number
23
total_row_count The total rows available for this data array. See paging Number
1002
Response Data Parameters
Parameter name Description Datatype Example
id The deployment ID String (GUID)
“5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b”
status Status of the deployment: activated, deactivated, or requested

For a full description of the various deployment statuses, see Deployment Status Enumeration below.
String (enumeratred)
“activated”
type proximity or audience String (enumerated)
“proximity”
design_id ID of the associated design String (GUID)
“38697e15-9e9e-4917-b55b-6431b99392f4<”/pre>
build_id The build ID String (GUID)
“a4d51e3b-ae95-4917-a7db-878255f334ea”
design_name The current name of the design. String
“LA Car Dealerships”
build_name Name of the build String
“LA Automotive”
filesize Size, in bytes, of the targeting file associated with the deployed build Number
1061822
source The inventory source (e.g. ad exchange) that was used to create the build object. Only applicable to designs of type “audience” where an inventory source must be specified to determine what inventory source to create the audience off of. Null for builds associated with designs of type “proximity”. String
“factual_dap”
price_cpm Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. JSON Object
{"base": “0.75”}
build_org Slug of the Org associated with the user who generated the build String
“factual”
build_org_id ID of the Org associated with the user who generated the build String (GUID)
“9303c65c-ad1f-4845-837f-aa87197cd448”
builder Email of the user who generated the build String
“user1@factual.com”
requester Email of the user who requested the deployment String
“user2@factual.com”
deployer Email of the Geopulse admin who approved the deployment request String
“admin@bigdsp.com”
build_date Timestamp representing when the build was successfully completed String (date)
“2016-03-01T05:22:33.000Z”
updated_at Timestamp representing when the deployment was most recently updated String (date)
“2016-03-03T00:45:30.000Z”
approved_at Timestamp representing when the deployment was initially marked as activated String (date)
“2016-03-03T00:45:30.000Z”
new_build Describes whether a deployment is associated with the first build of a given design. True = first version of a design Boolean
true
tags Deployment tags associated with the deployment String
“large,europe”
target Name of the target associated with the deployment String
“Big DSP OnPrem”
target_id ID of the deployment target String (GUID)
“aaffc17d-fd80-34aa-22bc-32133edf88b1”
download_path URL to download the deployed file. Not available for all deployment target types String (URL)
https://api.factual.com/geopulse/deployments/f144789c-6cb6-48a8-a5aa-3ab1e052e2a2/download
sets Array of sets in the build associated with the deployment JSON Array
sets[row].set_id The id of the set String (GUID)
“d151ea2c-9879-460c-a169-77a0de9ec3c5”
sets[row].set_name The name of the set String
“Used Car Dealers”
sets[row].targeting_code The targeting code associated with the set String
“cars_1000m”


Reject a Requested Deployment

Reject a deployment request. This may be used in the event that a Geopulse Admininistrator considers the targeting file associated with a deployment request to be too large for their infrastructure. Only deployments with status “requested” may be rejected.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/reject
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/reject HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Activate a Deployment

Activate a deployment. Any deployment may be activated, except for those with status “activated” already.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/activate
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/activate HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

tags=env1&KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Deactivate a Deployment

Deactivate a deployment, temporarily removing it from an On-Prem instance. This endpoint is provided to support lightweight toggling of deployed builds between active and inactive states. Only deployments of status “activated” can be deactivated.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/deactivate
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/deactivate HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Delete a Deployment

Delete a deployment, removing it permanently from an On-Prem server. At their core, “deactivate” and “delete” fulfill the same function, which is to remove a targeting file from memory on an On-Prem server, but where “deactivated” deployments will still show up in the Geopulse Management API results, “deleted” deployments do not show up, and should be considered as gone forever. Deleting deployments is primarily for situations where the end user or Geopulse Administrator know that this particular deployment will not be needed again, and deleting it (as opposed to deactivating it) can help to declutter the API results.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/delete
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/delete HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14

KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Tag a Deployment

Deployment tags, when used in conjunction with Geopulse On-Prem software, can help with server capacity management. At set up time, an On-Prem owner can define for any individual On-Prem server which deployment tags that server should be associated with. In this case, only targeting files associated with deployments that have the matching deployment tags will be loaded into memory on the particular On-Prem server. This can help to reduce required memory on your servers, as each server no longer needs to load every targeting file.

Adding deployment tags is desctructive of previous tags, so making this call will always overwrite the earlier list of tags.

Endpoint
https://api.factual.com/geopulse/deployments/(deployment id)/tag
  • This endpoint only accepts POST requests.
  • Replace (deployment Id) with the deployment id.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/deployments/89aa8acb-4563-4817-9051-2424aa632f20/tag HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26

tags=env1&KEY=my_api_key
Request Parameters
Parameter name Description Datatype Example
*tags The defined deployment tags String (comma delimited)
tags=large,europe
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c
*Required
Response Parameters
Parameter name Description Datatype Example
version The version of the API response. Number
4
status The status of the API response. String
“OK”


Common Conventions
paging

For API calls that return large volumes of data, the Factual API implements a paging system. Each API call will return one “page” of data, which includes a limited number of rows of data, offset from the start of the entire list of available data.

For example:

  • The first 10 rows would be identified by limit=10 and offset=0.
  • The next 10 rows would be identified by limit=10 and offset=10.

Paging parameters are used in conjunction with any other parameters that may filter a list down. So, for example, if you request a list of designs filtered to just proximity designs, you’ll get the first 10 proximity designs, then the next 10. There won’t be any “holes” in the result set where audience designs would have slotted chronologically.

Grant

Introduction

The Geopulse Grant API enables you to apply a visibility tag to a Geopulse design in order to provide a filter for visibility. This is typically used for creating custom permissions in the Geopulse Embed use case, and as a flexible tagging system, permissions can be as simple or complex as needed.

By default, a standard Geopulse user will be able to see all of the designs that they have created themselves. However, many Factual partners have requirements for more granular, complex permissions on designs. For example, perhaps a Factual partner wants all users from the same company to see any design created by a user from that same company. This can be done using visibility tags in conjunction with server side API calls made by a Geopulse Admin level user. See Geopulse Management APIs for a more complete example of how to use visibility tags to retrieve lists of designs filtered by visibility tag.

Example worflow:

  • User A is a member of “Sample, Inc.”
  • User A creates a new Geopulse Proximity Design, “Design XYZ” and saves it.
  • Factual Partner uses the Grant API call to assign “Design XYZ” the visibility tag “sample_inc”
  • When User B comes to the Factual Partner UI, partner makes a server side call to list all designs associated with the tag “sample_inc”, and lists these as valid designs for User B to interact with.

Note: Maintaining the mapping between which users should be associated with which visibility tags is dependent on the Fatual partner system. Factual does not maintain mappings of users to visibility tags.

Endpoint

https://api.factual.com/geopulse/designs/(design id)/grant

Syntax

  • This endpoint only accepts POST requests.
  • Replace (design id) with the id of the design you are granting visibility tags to.
  • Request Parameters should be URL encoded and POSTed as the body of the request.
  • The Content-Type for this request should be set to application/x-www-form-urlencoded.

Example

POST /geopulse/designs/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/grant HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67

visibility=pepsi%2Cdiet_coke&KEY=my_api_key

Request Parameters

Parameter name Description Datatype Example
 visibility Set of sluggified tags that you are assigning visibility for this design for. comma-delimited array of Strings
visibility=pepsi,diet_coke
*KEY Your API Key. Note the KEY parameter name must be declared in all caps. String
KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c

Notes on the visibility parameter:

  • visibility takes one or more tags which will be appled to the design. When accessing the deployment list API using the corresponding visibility tag, only designs with matching tags will be returned.
  • When tags are appled to visibility, the results will be OR’d. In otherwords, if a design has tags A and B applied to it, and you attempt to list all designs with tags B or C, the design will be returned as a match.
  • Pre-existing tags will be overwritten.
  • visibility tags will be sluggified.
    • Acceptable tags may use the characters a-z, A-Z, 0-9, and the underscore (‘_’) character. No whitespace is allowed.
    • Unacceptable characters will be transformed as follows: punction characters will be ignored, unicode letters transformed to the closest Arabic match, white space trimmed from the ends or replaced by underscore otherwise.
  • visibility tags are case sensitive.

Response Parameters

Parameter name Description Datatype Example
version The version of the API response. Integer
4
status The status of the response. String
“ok”
Example response:
{
  "version": 4,
  "status": "ok"
}

Sample

This API is in Beta.

The Sample API helps you do reach estimation for Geopulse Proximity and Audience designs, where your estimate requires subsetting sample data outside of Factual.

  • For Proximity, you provide sample geo points (grouped as you see fit) and a Proximity design id. Factual tests each sample, and returns a count of matches against each set of geofences in your design, as well as against all specified targeting codes.
  • For Audience Sets, you provide an Audience Set design id. Factual will return sample sets of representative conforming device ids. The number of device ids will always be uniform (1,000). However, if a set has been designed too strictly for a statistically relevant set of devices to be found, no devices ids will be returned.

Workflow

Working with the Sample API is a three step process:

  1. Request the samples or sample test
  2. Poll for progress
  3. Request the results

Request Samples or a Sample Test

There are separate endpoints for testing samples against Proximity designs and requesting sample Audience Sets, detailed below.

 

Audience Sets

Send a GET request with your design Id:

https://api.factual.com/geopulse/audience/designs/<designId>/sample
  • Replace <designId> with the unique ID of the design you are testing against. The ‘<’ and ‘>’ should be omitted.

 

Proximity

Send a POST request with your design Id to:

https://api.factual.com/geopulse/proximity/designs/<designId>/test
  • Replace <designId> with the unique ID of the design you are testing against. The ‘<’ and ‘>’ should be omitted.
Providing test lat/lngs

In the case of Proximity, you must POST sample sets of lat/lng points to be tested to the endpoint:

POST /geopulse/proximity/designs/70e9835d-cd56-448f-a107-422c1bfe20cc/test HTTP/1.1
Host: api.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 218

samples={"women18-24":[[34.058679,-118.416733],[34.060386,-118.418536]],"men18-24":[[34.060386,-118.418536]]}

Note: The body content in the example above is shown without URL encoding. In practice the content MUST be url encoded, and the content-length would reflect the encoded length.

A few notes:

  • The body must contain a samples parameter, containing a valid JSON map.
  • Each key in the JSON map may be a string of your own choosing. They’ll be used to identify counts of lat/lng samples against matched sets when collecting the results.
  • Each key must be mapped to an array of arrays.
  • Each sub array must contain exactly [latitude,longitude].
  • Latitude and longitude must be expressed as decimal numbers.
  • White space is OK, as long as it adheres to the JSON specification.
  • Content-Length should be calculated based on UTF-8 encoding of the body. E.g., this is a double-byte encoding so it would be twice the char count.
  • Content-Type must be application/x-www-form-urlencoded
  • The maximum number of points that may be submitted for a single estimate is 100,000.

 

Successful Response

For both Proximity and Audience requests, a successful (200) response will contain a JSON response in the body similar to the following:

{
  "version":4,
  "status":"ok",
  "response":
  {
    "taskId":"api-150615-094450-wukeki-035"
  }
}

Notes:

  • The taskId can be used to poll for progress or to request the final results.
  • You should expect the taskId will have a limited lifespan of no greater than 1 day.

 

Failure Responses

The following are potential error codes and the likely reasons for the error.

HTTP Response Code Explanation
400 There’s a syntax error in the JSON formatting of the data being passed into the endpoint (Proximity only) that prevents Factual from parsing it.
401 You don’t have access to the specified design.
404 The design does not exist (and never has), or (alternately) something else in the route is misspelled/incorrect.
410 The design has been deleted.
413 The volume of data being submitted for evaluation is too large.
429 You’ve exceeded the API quota for your API key for the current day.
500 You’ve hit an error that we’ve never considered.

In any case you receive one of these errors, the body of the response may contain a more verbose explanation similar to this:

{
  "version":4,
  "status":"error",
  "type":"Auth",
  "message":"the api key provided is invalid."
}

Polling for Progress

Once you’ve requested a set of Audience samples or a test against your Proximity samples, you can poll for progress, for the purpose of generating a progress bar, etc.

To poll for the latest progress, make an HTTPS GET request as follows:

https://api.factual.com/tasks/<taskId>/status
  • Replace <taskId> with the task Id returned from the sample or test call. The ‘<’ and ‘>’ should be omitted.

 

Successful Response

200 responses will contain a JSON response in the body similar to the following:

{
  "version":4,
  "status":"ok",
  "response":
  {
    "started":1397564362,
    "current":1397564882,
    "status":"processing",
    "progress":33
  }
}

Notes:

  • started returns the epoch time in seconds when the process was initiated
  • current returns the current epoch time, as seen by the server performing the process
  • status will be one of pending, processing, or complete
  • progress will be an integer between 0 and 100, representing an approximation of the percent of the way to completion, where 0 is not started and 100 is complete.

 

Failure Responses
HTTP Response Code Explanation
401 You don’t have access to the process specified by the task Id.
404 No process for the task Id exists (and never has). Alternately, something else in the route is misspelled/incorrect.
410 The task Id has been expired.
429 You’ve exceeded the API quota for your API key for the current day.
500 You’ve hit an error that we’ve never considered.

As with the sample and test API calls, error responses will likely contain more verbose information in the response body.

Request the Results

Once the status has returned as complete, you may make an HTTPS GET request for the results:

https://api.factual.com/tasks/<taskId>/results
  • Replace <taskId> with the task id returned from the sample or test call. The ‘<’ and ‘>’ should be omitted.

 

Successful Audience Response

For Audience sample requests, a 200 response will contain a JSON response in the body similar to the following:

{
  "version":4,
  "status":"ok",
  "responseType":"audience-samples",
  "response":
  {
    "design":
    {
      "id":"fff70d02-bcbf-463f-b3c6-f2fd3e7ba90fe",
      "name":"Target Shoppers",
      "type":"audience"
    },
    "sets":
    [
      {
        "setId":"9ec4b6f8-48e1-4da3-b3e1-34dafc999964",
        "setName":"women 18-24",
        "targetingCode":"WOMEN",
        "devices":
        [
          "cf23df2207d99a74fbe169e3eba035e633b65d94",
          "a74fbe169e3e3eba035e6333df2207d99ba035e6",
          ... // 1,000 of these!
        ]
      },
      {
        "setId":"6f89ec4b-4856-4323-11e1-fc99994da6e",
        "setName":"men 18-24",
        "targetingCode":"MEN",
        "devices":[] // Empty set means your set definition is too strict!
      }
    ]
  }
}

Notes:

  • Sets for which devices are available will always return exactly 1,000 representative device Ids. Identical device Ids will be returned for repeated requests.
  • Sets which are defined too strictly for a statistically relevant set of samples to be found will result in no device Ids being returned.

 

Successful Proximity Response

For testing Proximity samples, a 200 response will contain a JSON response in the body similar to the following:

{
  "version":4,
  "status":"ok",
  "responseType":"proximity-sample-test",
  "response":
  {
    "design":
    {
       "id":"f5170d02-bcbf-463f-b3c6-ba906f2fd3e7",
       "name":"Clothing Retail",
       "type":"proximity"
    },
    "matches":
    {
      "women18-24":
      {
        "totalMatches":301,
        "sets":
        [
          {
            "setId":"3d5c7382-53f7-417c-93b5-cafc566a3d22",
            "setName": "The Gap",
            "targetingCode":"RETAIL",
            "count":73
          },
          {
            "setId":"9ec4b6f8-48e1-4da3-b3e1-34dafc999964",
            "setName": "Banana Republic",
            "targetingCode":"RETAIL",
            "count":228
          }
        ],
        "targetingCodes":
        [
  	  {
  	    "targetingCode":"RETAIL",
	    "count":301
	  }
        ]
      },
      "men18-24":
      {
        "totalMatches":50,
        "sets":
        [
          {
            "setId":"3d5c7382-53f7-417c-93b5-cafc566a3d22",
            "setName": "The Gap",
            "targetingCode":"RETAIL",
            "count":17
          },
          {
            "setId":"9ec4b6f8-48e1-4da3-b3e1-34dafc999964",
            "setName": "Banana Republic",
            "targetingCode":"RETAIL",
            "count":33
          }
        ],
        "targetingCodes":
        [
	  {
	    "targetingCode":"RETAIL",
	    "count":50
	  }
        ]
      }
    }
  }
}

Notes:

  • There may be future key/value pairs in each set id/targeting code hash.
  • Matches in the sets object contain setNames and targetingCodes for convenience.
  • Sets and targeting codes that hit on no sample data will not be returned. E.g., you will never receive a count of zero.

 

Error Responses
HTTP Response Code Explanation
401 You don’t have access to the process specified by the task Id.
404 The task id does not exist, or (alternately) something else in the route is misspelled/incorrect. Additionally, if the progress of your sample request is not yet complete, you will receive a 404.
410 The sample request has been expired.
429 You’ve exceeded the API quota for your API key for the current day. Note that the polling requests for status are counted separately from the reach requests. Accidentally polling too many times should never disable you from accessing the result.
500 You’ve hit an error that we’ve never considered.

Audience

Introduction

This document will help you navigate Factual’s Audience API. The Audience API provides the following functionality:

  • provide data signals by which Factual can build Audience profiles for you
  • enable customized responses to Factual APIs, by leveraging Audience profiles

Geopulse customers: this document is limited to using the V4 API to write Audience data to Factual. For comprehensive documentation on Audience and Proximity products, please contact Factual directly.

Basics

The Factual Audience API can be called directly from mobile devices, indirectly by way of a proxy server, or run in batches in non-real-time. Requests are transmitted over HTTP, similar to the rest of Factual’s V4 API. In fact, in many cases, the simplest way to utilize the Audience API is by augmenting other real-time requests like Search or Geotag.

There are three primary containers for passing Audience data to Factual: Device, App, and Event.

The data elements that can be passed into each of these containers is broad and, in many cases, you will not be populating most of them.

Examples

Example 1: submitting a simple Audience event to Factual1
https://api.factual.com/audience?
  app=
  {
    "name":"My Awesome App",
    "id":"A5B6C7D8E9.com.mydomain.myapp",
  }&
  device=
  {
    "device_id":"AAAAAAAAA-BBBB-CCCC-1111-222222220000",
    "os":"iOS","os_version":"8.1","make":"apple","model":"iPhone6,1"
  }&
  event=
  {
    "time":1417557439,
    "latitude":34.058614,
    "longitude":-118.41687,
    "event":"APP_START"
  }&
  KEY=your_API_key_here
Example 2: submitting an Audience event to Factual in tandem with a Geotag API call1
https://api.factual.com/geocode?
  latitude=34.058614&
  longitude=-118.41687&
  app=
  {
    "name":"My Awesome App",
    "id":"A5B6C7D8E9.com.mydomain.myapp",
  }&
  device=
  {
    "device_id":"AAAAAAAAA-BBBB-CCCC-1111-222222220000",
    "os":"iOS","os_version":"8.1","make":"apple","model":"iPhone6,1"
  }&
  event=
  {
    "time":1417557439,
    "latitude":34.058614,
    "longitude":-118.41687,
    "event":"ACTIVITY_MOVED"
  }&
  KEY=your_API_key_here

1 URL encoding omitted and liberal use of line feeds/white space for clarity. In practice the app, device, and event parameters should be individual URL encoded.

Requests

The Factual API is case sensitive:

  • parameter names must be exactly as shown, below
  • enumerated values shown in ALL CAPS should be provided exactly as shown, below


Required Parameters

Every Audience request requires the device and event parameters. The app and strict parameters are optional.

The following are required elements of the app, device, and event parameters for a valid submission:

app device event
name
id
device_id event
time
latitude
longitude


Device

The device parameter contains information about device hardware and software.

element Name description datatype example
*device_id2 device id string
"AAAAAAAAA-BBBB-CCCC-1111-222222220000"
 device_class3 class of device string
"MOBILE"
 os The OS the app is running on string
"iOS"
 os_version The version of the OS the app is running on string
"8.1"
 make The maker of the device string
"Apple"
 model The model number of the device string
"iPhone6,1"
 local_id Any Id used by the developer to identify the device string
 data An arbitrary container of data elements for custom use. JSON object

Required elements are marked with asterisks (*)

2 There are four options for populating the device_id : Apple IDFA (post iOS 7), Apple UDID (pre iOS 7), Google AID, or manually generating a random GUID and storing it locally for future submissions. Note that Apple does not allow accessing the IDFA if your app is not explicitly showing advertisements.

3 device_class should be one of the following:

device_class description
MOBILE Mobile device
TABLET Tablet computer
DESKTOP Desktop or laptop computer
TV Smart television set or device
CONSOLE Consumer gaming console
DASHBOARD Embedded automotive applications


App

The app parameter contains information identifying your app.

element Name description datatype example
*name Name of the app. string
"My App"
*id4 Unique identifier of the application. string iOS:
"A5B6C7D8E9.com.mydomain.myapp"

Android
"com.mydomain.myapp"

RTB:
"agltFwcBb3B1Yi1pbmNyDAsSA0izmcMUDA"

GUID:
"fa83108b-4f4b-5432-a362-2e887effbb50"
 publisher5 The publisher of the app. JSON object
{"id":"yEAsSBagltb3B1Yi1pbmN0FjY291bnQYjKKZFAw","name":"Software, Inc."}
 ver Version of the app. string
"1.0b"
 content Identifies app content present when the event transpired JSON object
 region The device user’s chosen region setting string
 language The device user’s chosen language setting string
 input_modes The active keyboards currently available. array of strings
 data An arbitrary container of data elements for custom use. JSON object

Required elements are marked with asterisks (*)

4 Most appropriate available option of: Apple App Id, Android package name, or IAB RTB app.id string (section 3.3.6).

5 The IAB RTB specified app.publisher object (section 3.3.6).


Event

Events contain time-stamped data relating to any event to be transmitted to Factual. For example:

  • app startup
  • a change of location
  • displaying an ad
  • a user clicking through an ad
element Name description datatype example
*event6 The type of event being recorded string
"APP_START"
*time date and time of the event, in epoch time seconds, when this event started int
1417557439
 duration milliseconds this event encapsulates where no other parameters change. int
 latitude latitude (in decimal format) float
34.058614
 longitude longitude (in decimal format) float
-118.416870
 ll_accuracy geo accuracy, in meters float
10.1
 geocode_type8 The method of geolocation used to generate the lat/lng. string
"GPS"
 alt altitude, in meters float
100.5
 alt_accuracy altitude accuracy, in meters float
4.2
 mps speed, in meters per second float
0.0
 bearing direction of travel, degrees clockwise from north float
349.1
 device_orientation orientation of device, degrees clockwise from north float
17.6
 connection_type7 The type of data connection the device currently is using. string
 network Name of wifi connection string
 ssid wifi ssid string
 bssid wifi bssid string
 mac_address string
 ip ip address of device string
 provider network service provider string
"AT&T"
 battery_percent The reported percent of battery remaining at the time of the event. float
 battery_is_charging True if the battery is currently charging, false otherwise. Null if you don’t know. boolean
 data An arbitrary set of data to support the event, limited to 5000 characters of data. JSON object

Required elements are marked with asterisks (*)

6 event should be one of the following:

AD_BID_REQUEST AD_BID_RESPONSE AD_WIN_NOTICE AD_SERVED
AD_CLICK AD_CONVERSION MATCHED_PROXIMITY MATCHED_AUDIENCE
MATCHED_AUDIENCE_SET MATCHED_COMPUTED MATCHED_AND_CONTROL_EXCLUSION APP_START
APP_POLL APP_REQUEST APP_INSTALL APP_ACCOUNT_CREATION
APP_ACCOUNT_ACTIVATION APP_PURCHASE APP_IN_APP_PURCHASE APP_START_EXTERNAL_APP
APP_OPEN_LINK APP_CLICK APP_SEARCH APP_REQUEST_DIRECTIONS
ACTIVITY_DRIVING ACTIVITY_ON_BICYCLE ACTIVITY_ON_FOOT ACTIVITY_MOVED
DEV_MISC DEV_NETWORK_UPDATE DEV_BATTERY_STATE_UPDATE DEV_BATTERY_LEVEL_UPDATE
FACTUAL_VERIFY_ACTIVE FACTUAL_VERIFY_PASSIVE

7 connection_type should be one of the following:

connection type description
CELL Cellular data access
WIFI Wifi data acces
WIRED Data access through that cable thing on the back of your computer
RADIO Data access via any other radio device

8 geocode_type should be one of the following:

geocode type description
GPS Location from a GPS sensor
WIFI Location based on the known location of a WIFI router
REVERSE_IP Location gleaned from a reverse IP lookup
CELL_TOWER Location from cell tower triangulation


First Party Data

You can transmit first party data using the appropriate data object in the app, device, or event objects. For example:

{
  "device":{},
  "event":{}
}
Event Lists

Event lists bundle multiple events together for bulk transmission on account of a single device. The event_list parameter takes a JSON array of Event objects:

event_list=
  [
    {
      "time":1417557439,
      "duration":29,
      "latitude":34.058614,
      "longitude":-118.416870,
      "event":"APP_POLL"
    },
    {
      "time":1417557468,
      "latitude":34.058611,
      "longitude":-118.416184,
      "event":"ACTIVITY_ON_FOOT"
    }
  ]
  • Event lists should be accompanied with app and device data, that are uniformly applied to all events in the list.
  • To reduce payload sizes, it is highly recommended that multiple geo-location samples without notable activity be condensed into single events in the event list, with a duration spent (in seconds) at the same approximate location.
  • If both the event and _event_list parameters are passed, the single event will be merged with the event list.

Any errors in a list of event are returned, indexed to the row. Note that, if you included both the event and event_list parameter, the event will be inserted as the zeroth element of the list.

{
  "version":4,
  "status":"error",
  "error_type":"InvalidEventList",
  "message_list":
  [
    {"row":0,"message":"The 'event' parameter is missing the required element 'event'."},
    {"row":5,"message":"event.geocode_type contains an invalid value."}
  ]
}


Strict

Audience takes a strict parameter. If strict=true, then any JSON attribute of device, app, or event that is matched against an enumeration will be validated, returning an error if the value is not within the enumeration. If strict=false it will pass without error.

Responses

The Factual API responds with:

  • An HTTP response code (200, 400, etc.)
  • A JSON packet in the HTTP response body
  • HTTP Header data


Successful Response
When making a GET or POST containing directly to the Audience endpoint

If your submission is valid, you’ll receive the following in the body of an HTTP 200 response:

{
  "version":4,
  "status":"ok"
}
When providing Audience data in tandem with another API call

If your submission is valid, you’ll simply receive the response related to the other API call you are making. E.g., a list of places you searched for.


Exceptional Responses

The following conditions will result in a 400 response, with more specific error information in the response body, as shown.

The device, or event parameter is missing:
{
  "version":4,
  "status":"error",
  "error_type":"InvalidRequest",
  "message":"The required parameter 'device' is missing."
}
The app, device, or event parameter contains invalid JSON:
{
  "version":4,
  "status":"error",
  "error_type":"InvalidRequest",
  "audience":"The 'app' parameter contains an improperly formatted JSON payload."
}
The app, device, or event parameter is missing a required JSON element:
{
  "version":4,
  "status":"error",
  "error_type":"InvalidRequest",
  "audience":"The 'device' parameter is missing the required element 'name'."
}
An enumerated value (device.device_class, event.event, event.geocode_type) doesn’t match the valid list of values:
{
  "version":4,
  "status":"error",
  "error_type":"InvalidValue",
  "audience":"event.geocode_type contains an invalid value."
}


Error Responses
HTTP Response Code Explanation
401 You don’t have access to the process specified by the Audience API.
404 There is an error in the URL portion of your request.
429 You’ve exceeded the API quota for your API key for the current day.
500 You’ve hit an error that we’ve never considered.