Export APIs

Audience Exports

Audience Exports allows you to export Audiences created in the Localytics Dashboard for engagement in other platforms.

Introduction

Localytics empowers marketers to create rich and granular audiences via its industry leading segmentation tools. Our platform then uses the audiences to drive personalized and highly targeted mobile engagement, that positively impacts our customer’s most valuable business KPI’s. Our customers have found tremendous value in this process, however, often times they want to use this segmentation to drive engagement in non-mobile channels like email or online advertising. For example, “create an audience of all users that have made an in-app purchase in the past 7 days, but opted out of push, so that I can automate sending them a customer loyalty email every Wednesday morning”. Audience Exports was built to satisfy this and other similar use cases.

Getting Started

Audience Exports accepts HTTP GET requests authenticated with an API Key/Secret. Every request must include the following information:

  • Authentication - Org level API key and secret that allows Localytics to authenticate your request.
  • Audience information - Audience specific parameters that allows Localytics to properly identify the audience and format the output.

Configuring Audiences for Export

Before making a request to the API you must enable the audience you want to export via the Localytics Dashboard. To enable a given audience for the first time (after creating the audience):

  1. Navigate to the Audiences Screen and find the Audience you want to enable
  2. Click the Action menu and click Enable Audience Export
  3. From the pop-up modal select output type and click Enable

Managing Audience Exports

To disable or re-enable exports you must visit Data Export in the Localytics Dashboard.

Implementation Details

Before integrating, here are some details you need to know:

  • Audiences are refreshed daily starting at 8 a.m. EST and typically finish within an hour.
  • A maximum of 5 audiences, per organization, can be available to the API at a time with an Enterprise Analytics or Enterprise Marketing subscription.
    • A maximum of 20 Audiences, per org, can be available to the API with an Enterprise Remarketing subscription
  • You must first create and enable the audiences in the Localytics Dashboard before attempting to request them via the API.
  • Deleting the audience in the Localytics Dashboard will stop it from refreshing and make it unavailable via the API
    • Audiences not requested in a 45 day period will also stop refreshing and be made unavailable via the API.

Audience Exports Transactions

Endpoint

The base URL for all requests is: 

https://api.localytics.com/v1/exports/audiences/:audience_id/:identifier_type

Authentication

Audience Exports uses Basic Access Authentication. You can use your organization’s API Key/Secret to authenticate the request. These are the same credentials you use to authenticate requests to the Localytics Profile API, Push API, and Events API.

You can find your organization’s API Key/Secret by navigating to the API Keys section of the Account page in the Localytics Dashboard.

Rate Limits

Audience Exports enforces the following rate limits per API Key:

  • 50 requests per minute.

Audience Request Parameters

Authentication Parameters

Parameter Required? Description
api_key Required This is the customer key assigned by Localytics. Your key can be found here.

Example: 7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee
api_secret Required This is the customer secret assigned by Localytics. Your key can be found here.

Example: 19c2aac0000a23803e9676a-97b8814a-75f4-11e6-bf23-008d99911b00

Audience Parameters

Parameter Required? Description
audience_id Required This is a Localytics-generated identifier for the audience being requested. It is unique to a given audience. The audience_id will be formatted as a positive integer.

This can be found beside the Audience name in the enablement modal or in Data Exports

Example: 153829
identifier_type Required This is the type of identifier that Audience Exports will return — for example, Apple Identifier for Advertising (IDFA) or Localytics Customer ID.

The identifier_type value should be one of the following:
Identifier Identifier_type
Apple Identifier for Advertising (IDFA) idfa
Google Advertising ID (GAID) gaid
Email Address email
Customer ID customer_id

Example

Here is an example with IDFA as the identifier type. 

curl -L https://[api_key]:[api_secret]@api.localytics.com/v1/exports/audiences/153829/idfa

Response

Audience Exports will return a 302 response code with a location header pointing to a file containing the results, if your request is formatted correctly.

Example Response

  HTTP/1.1 302 Found
  Date: Wed, 30 Nov 2016 14:47:38 GMT
  Content-Length: 0
  Connection: keep-alive
  Location: https://auditorium-cache-prodprimary.s3.amazonaws.com/queries/fae3e6102993ef78d079ca16688ecdea35d5dfe2273986c1fafb500ea3ab012e-v1/c14ffba3-bfe2-4e5c-a16b-cd1f6850c5dd?AWSAccessKeyId=AKIAIT2WF7LISGBN23SQ&Expires=1480689996&Signature=0e6QA2ec8wEf%2FxAo6iYM47RinYk%3D

Redirect Output

The redirect output will be a JSON formatted file where each row contains an identifier, however, the file will not contain a header row. For example: 

  {"IDFA":"E751D492-9BB5-4A6E-B7CA-B0DF980F63FA"}
  {"IDFA":"AF83D440-A7AF-4504-A77C-62FE2FCEF661"}
  {"IDFA":"33882069-6ABE-4ACF-8FA0-41F3DA418560"}
  {"IDFA":"975BD354-D3B8-4DFE-9036-E3ECFCA5B57F"}
  …

Requesting a List of Available Audiences

Endpoint

The base URL is: 

https://api.localytics.com/v1/exports/audiences

Response

An Audience list request will result in a JSON formatted response with the following information:

Parameter Required? Description
id Required The identifier of the export job.
name Required The name of the audience being exported
source_type Required The object being exported (ex. audience).
source_id Required The identifier of the object being exported.
job_type Required The type of data being exported (ex. idfa).
results_generated_at Optional The last time the results for this export were generated. If missing no results have been generated yet.
results_count Required Number of rows in the export
results_generated_at Required The date that the result set expires.
last_requested_at Optional The last time the result for this export were requested. If they have never been requested this value will be missing.

Sample Response

  [
    {
    "id": 6,
    "name": "Localytics",
    "source_type": "audiences",
    "source_id": "45644",
    "job_type": "idfa",
    "last_requested_at": "2017-02-13T14:30:47Z",
    "results_count": 6705543,
    "results_generated_at": "2017-02-13T12:30:43Z",
    "results_expire_at": "2017-06-02T11:06:39Z"
  },
  {
    "id": 7,
    "name": "Localytics2",
    "source_type": "audiences",
    "source_id": "4478",
    "job_type": "email",
    "results_count": 5105543,
    "results_generated_at": "2017-02-13T12:30:48Z",
    "results_expire_at": "2017-06-02T11:06:39Z"
  }
  ...
]

HTTP Response Codes

Audience Exports return the following HTTP response codes:

Code Description
302 The audience request was successful and Localytics will redirect the requestor to a file containing the export.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not match with a Localytics Org or the Org doesn’t have access to the specified audience.
404 The source type is unknown. Remember, it should always be "audience" when using Audience Exports.
429 You’ve met your 10 request per minute limitation and are now being throttled.

Version History

Version Date Change Summary
0.5 01/18/2017 Beta release version.
1.0 04/06/2017 GA release version. Includes self-serve Dashboard management, audience list request functionality, and new URL structure.
1.5 05/30/2017 Added audience name and size to the audience list response

Profile Exports

Profile Exports allows you to export, in bulk, preferences and behaviors of users associated with your app for engagement and analysis in other platforms.

Introduction

The Localytics Engagement Platform enables marketers to collect information about their user’s preferences, behaviors and interactions to be used in targeting and segmentation. A set of these data points for an individual user is a Profile. Profiles are used throughout our platform, and are increasingly becoming an integration point for our marketing cloud, customer relationship management system and other ecosystem partners. Localytics Profile Exports is a RESTful web service that enables our customers and partners to more rapidly build these user level integrations without a significant engineering investment.

Getting Started

Profile Exports accepts HTTP GET requests authenticated with an API Key/Secret. Every request must include the following information:

  • Authentication - Org level API key and secret that allows Localytics to authenticate your request.
  • Profile ID - Uniquely identifies the set of Profiles being requested.

Configuring Profiles for Export

Before making a request to the API you must enable the set of Profiles you want to export via the Localytics Dashboard. To enable a given set of Profiles for the first time:

  1. Navigate to the Profiles Screen of the Application or Organization
  2. Click the Action menu and click Enable Profile Exports
  3. From the pop-up modal select the Application or Organization, Export Type and click Enable

Managing Profile Exports

To disable or re-enable exports you must visit Data Export in the Localytics Dashboard.

Implementation Details

Before integrating, here are some details you need to know:

  • Profile Exports are refreshed daily starting at 8 a.m. EST and typically finish within an hour.
  • A maximum of 5 Profile Exports, per organization, can be available to the API at a time with an Enterprise Analytics or Enterprise Marketing subscription.
  • You must first enable a particular Profile Export before attempting to request it via the API.
  • Profile Exports not requested in a 45 day period will stop being refreshed and be made unavailable via the API.

Profile Exports Transactions

Endpoint

The base URL for all requests is: 

https://api.localytics.com/v1/exports/profiles/:profiledb_id/:job_type

Authentication

Profile Exports uses Basic Access Authentication. You can use your organization’s API Key/Secret to authenticate the request. These are the same credentials you use to authenticate requests to the Localytics Profile API, Push API, and Events API.

You can find your organization’s API Key/Secret by navigating to the API Keys section of the Account page in the Localytics Dashboard.

Rate Limits

Profile Exports enforces the following rate limits per API Key:

  • 50 requests per minute.

Profile Exports Request Parameters

Authentication Parameters

Parameter Required? Description
api_key Required This is the customer key assigned by Localytics. Your key can be found here.

Example: 7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee
api_secret Required This is the customer secret assigned by Localytics. Your key can be found here.

Example: 19c2aac0000a23803e9676a-97b8814a-75f4-11e6-bf23-008d99911b00

Export Parameters

Parameter Required? Description
profiledb_id Required This is a Localytics-generated identifier for the set of Profiles being exported. The profiledb_id will be formatted as a positive integer, and can be found here for apps and here for your org, both in the Settings screen of your Localytics Dashboard.

This can be found beside the app name in the Settings Screen

Example: 6012
job_type Required This is type of Profile Export that will be return. You can request a full export of all Profiles within a given ProfileDB ID or changes since the last time you requested an export for a given ProfileDB ID.

The job_type value must be one of the following:
Job Job_type
Export of entire Profile set profile
Export of changes since last request profile_changes

Example

Here is an example with profile_changes as the job type. 

curl -L https://[api_key]:[api_secret]@api.localytics.com/v1/exports/profiles/6012/profile_changes

Response

Profile Exports will return a 302 response code with a location header pointing to a file containing the results, if your request is formatted correctly.

Example Response

  HTTP/1.1 302 Found
  Date: Wed, 30 Nov 2016 14:47:38 GMT
  Content-Length: 0
  Connection: keep-alive
  Location: https://auditorium-cache-prodprimary.s3.amazonaws.com/queries/fae3e6102993ef78d079ca16688ecdea35d5dfe2273986c1fafb500ea3ab012e-v1/c14ffba3-bfe2-4e5c-a16b-cd1f6850c5dd?AWSAccessKeyId=AKIAIT2WF7LISGBN23SQ&Expires=1480689996&Signature=0e6QA2ec8wEf%2FxAo6iYM47RinYk%3D

Redirect Output

The redirect output will be a JSON formatted file where each row contains an identifier, however, the file will not contain a header row. For example: 

  {"_ll.language":"en", "favorite_place":"Mohit’s Crib"}
  {"_ll.language":"en", "favorite_place":"Paris"}
  {"_ll.language":"en", "favorite_place":"Rejuvenation Room"}}
  {"_ll.language":"en", "favorite_place":"Boston"}
  …

  {"deletes":{"attributes":["some_attrib1", "some_attrib2"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"_ll.country":"Spain", "favorite_place":"Boston"}}
  {"profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"_ll.country":"USA"}}
  {"deletes":{"attributes":["some_attrib1"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}}
  {"deletes":{"attributes":["some_attrib2"]}, "profile":{"_ll.raw_customer_id":"my_cust_id", "profiledb_id": 60}, "updates":{"favorite_place":"Boston"}} 
  ...

Requesting a List of Available Exports

Endpoint

The base URL is: 

https://api.localytics.com/v1/exports/profiles

Response

An Audience list request will result in a JSON formatted response with the following information:

Parameter Required? Description
id Required The identifier of the export job.
name Required The name of the export
source_type Required The object being exported (ex. profile).
source_id Required The identifier of the object being exported.
job_type Required The type of data being exported (ex. profile_changes).
results_generated_at Optional The last time the results for this export were generated. If missing no results have been generated yet.
results_count Required The number of rows being exported.
results_expire_at Required The date that the result set expires.
last_requested_at Optional The last time the result for this export were requested. If they have never been requested this value will be missing.

Sample Response

  [
    {
    "id": 191,
    "name": "Localyticss_ios_app",
    "source_type": "profile",
    "source_id": "13724",
    "job_type": "profile_changes",
    "last_requested_at": "2017-02-13T14:30:47Z",
    "results_generated_at": "2017-02-13T12:30:43Z",
    "results_count": 43543,
    "results_expire_at": "2017-06-02T11:06:39Z"
  },
  {
    "id": 374,
    "name": "Localytics_android_app",
    "source_type": "profile",
    "source_id": "209478",
    "job_type": "profile",
    "results_generated_at": "2017-02-13T12:30:48Z",
    "results_count": 7843,
    "results_expire_at": "2017-06-02T11:06:39Z"
  }
  ...
]

HTTP Response Codes

Profile Exports return the following HTTP response codes:

Code Description
302 The Export request was successful and Localytics will redirect the requestor to a file containing the export.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not match with a Localytics Org or the Org doesn’t have access to the specified Exports.
404 The source type is unknown. Remember, it should always be "profiles" when using Profile Exports.
429 You’ve met your 10 request per minute limitation and are now being throttled.

Version History

Version Date Change Summary
0.5 05/04/2017 Beta release version.
1.0 08/25/2017 GA release version. Includes self-serve dashboard.


Raw Log Exports

Introduction

To enable our customers to run deeper custom analytic queries, we give access to your raw data and let you load it into a data warehouse of your choosing. The processor produces what we refer to as the JSON logs; these contain a superset of data contained in our internal JSON logs. We upload the JSON logs to an AWS S3 bucket with hourly prefix keys, and customer log exports are split out from these hourly logs for export. Localytics Log Exports is a RESTful web service that enables our customers to access the raw data collected from their applications easily.

Consult with your account team or support for additional raw-log JSON schema details and field descriptions.

Getting Started

Log Exports accepts HTTP GET requests authenticated with an API Key/Secret. Every request must include:

  • Authentication - Org level API key and secret that allows Localytics to authenticate your request.

Implementation Details

Before integrating, it's important to note that:

  • The customer log exports are split out from these hourly logs. We take all of the events, sessions, and closes for an hour for a single app and put it in a gzipped file which we put in an AWS S3 bucket with the appropriate prefix and name.
  • These logs will be remove after 30 days.

Log Exports API

Requesting Logs For a Given Hour

Endpoint

The base URL for all requests is: 

https://api.localytics.com/v1/exports/analytics/logs/:app_uuid/:year/:month/:day/:hour

Authentication

Log Exports uses Basic Access Authentication. You can use your organization’s API Key/Secret to authenticate the request. These are the same credentials you use to authenticate requests to the Localytics Profile API, Push API, and Events API.

You can find your organization’s API Key/Secret by navigating to the API Keys section of the Account page in your Localytics Dashboard.

Rate Limits

Log Exports enforces the following rate limits per API Key:

  • 50 requests per minute

Log Exports Request Parameters

Authentication Parameters

Parameter Required? Description
api_key Required This is the customer key assigned by Localytics. Your key can be found in the API Keys section of the Account page in your Localytics Dashboard, or by following the link here.

Example: 7d2e3219e6f93bececb44b6-97b87de8-75f4-1100-bf23-000099911bee
api_secret Required This is the customer secret assigned by Localytics. Your key can be found in the API Keys section of the Account page in your Localytics Dashboard, or by following the link here.

Example: 19c2aac0000a23803e9676a-97b8814a-75f4-11e6-bf23-008d99911b00

Export Parameters

Parameter Required? Description
app_uuid Required Your Localytics App ID.

Example: 91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f
year Required Four digit year—e.g. 2018
month Required Month in 1(or 01) to 12
hour Required 24 hour schema — e.g. 0(or 00) to 23

Example

curl -i https://[api_key]:[api_secret]@api.localytics.com/v1/exports/analytics/logs/1bea53c5f15a26dff0a078f-2eedf7d6-fd41-11e3-4735-00a426b17dd8/2017/04/01/14

Response

Log Exports will return a 302 response code with a location header pointing to a file containing the results, if your request is formatted correctly.

Example Response

  HTTP/2 302
  date: Thu, 10 May 2018 19:27:39 GMT
  content-length: 0
  location: https://s3.amazonaws.com/exports.localytics.i-m/localytics/2017/04/01/1bea53c5f15a26dff0a078f-2eedf7d6-fd41-11e3-4735-00a426b17dd8/14.log.gz?x-amz-security-token=[token]

Redirect Output

The redirect output will be a JSON formatted file where each row contains a log row. For example: 

  {"device_uuid":"xxx","os_ver":"9.1","name":"updateWeather","lng":-100.92219,"device_new":false,"carrier":"AT&T","model":"iPad mini (2nd gen)","browser":"CFNetwork 758","app_ver":"1.1.3","uuid":"xxx","device_timezone":-18000,"advertising_id":"xxx","country":"us","at":"2017-04-01 14:02:39","language":"en","bundle_id":"com.localytics.WeatherVane","user_type":"anonymous","session_uuid":"xxx","nth":272,"app":"1bea53c5f15a26dff0a078f-2eedf7d6-fd41-11e3-4735-00a426b17dd8","install_uuid":"xxx","library_ver":"iOSa_3.8.0","type":"e","platform":"iPad","jailbroken":false,"limit_advertising":true,"birth_date":xxx,"customer_ids":{"customer_id":"[xxx]]"},"lat":32.701595}
  {"device_uuid":"xxx","os_ver":"9.1","lng":-100.92219,"device_new":false,"carrier":"AT&T","model":"iPad mini (2nd gen)","browser":"CFNetwork 758","app_ver":"1.1.3","uuid":"xxx","device_timezone":-18000,"advertising_id":"xxx","country":"us","at":"2017-04-01 14:02:39","language":"en","bundle_id":"com.localytics.WeatherVane","user_type":"anonymous","sec_since_last_session":134017,"nth":272,"app":"1bea53c5f15a26dff0a078f-2eedf7d6-fd41-11e3-4735-00a426b17dd8","install_uuid":"[xxx]]","library_ver":"iOSa_3.8.0","type":"s","platform":"iPad","jailbroken":false,"limit_advertising":true,"birth_date":xxx,"customer_ids":{"customer_id":"[xxx]]"},"lat":32.701595}
  …

HTTP Response Codes

Log Exports return the following HTTP response codes:

Code Description
302 The Export request was successful and Localytics will redirect the requestor to a file containing the export.
401 The provided authentication parameters were not valid.
403 The provided api credentials do not match with a Localytics Org or the Org doesn’t have access to the specified Exports.
404 If a request is made for an export that has not yet completed, or an invalid app ID or an app that does not have log exports set up
429 You’ve met your 50 request per minute limitation and are now being throttled.

Version History

Version Date Change Summary
v1 08/01/2017 GA release version.
v1.1 12/03/2018 Adds at_millis to log exports representing the UTC time in milliseconds since the epoch of an event. The device must be running SDK version 5.1 or higher for this field to have millisecond precision; devices below this will have xxxx000 rounded to the second.
v1.2 03/13/2019 Adds push_status to log exports representing how push notifications will be delivered to the device. Values are Provisional, Disabled, Enable (Delivered Quietly) or Enabled (Prominent).