Richie Ads Campaign Analytics API

Introduction

Richie Ads provides API access to the campaign analytics data that underpins our campaign reporting. The API responds at https://api.richie.fi/ and uses HTTP Basic Authentication with account credentials separate from the Richie Console credentials; please reach out to Richie Support to gain access to the API.

List Campaigns

GET /ads/v3/campaigns

The campaigns endpoint returns all campaigns the account credentials used in the request have access to. There is one optional query parameter:

The response includes an object for each campaign:

{
  "campaigns": [
    {
      "id": "cac2e29b-0e95-4c89-b5bd-9e1e00d9c388",
      "name": "Example Campaign 15 June 2019—22 June 2019",
      "reportUrl": "https://api.richie.fi/ads/v3/campaigns/cac2e29b-0e95-4c89-b5bd-9e1e00d9c388/report",
      "ads": [
        {
          "name": "ad name",
          "ad_uuid": "ad uuid",
          "preview": "https://url.to.preview.image"
        }
      ]
    },
    {
      "id": "6fba113b-089d-47d9-9943-bbf97f3950a7",
      "name": "Another Campaign 20190701",
      "reportUrl": "https://api.richie.fi/ads/v3/campaigns/6fba113b-089d-47d9-9943-bbf97f3950a7/report",
      "ads": [
        {
          "name": "another ad name",
          "ad_uuid": "another ad uuid",
          "preview": "https://url.to.preview.image"
        }
      ]
    }
  ],
  "lastModifiedTimestamp": 1562133501
}

To continuously update campaign data on your systems, you can poll this endpoint by storing and roundtripping the lastModifiedTimestamp value to the with_events_since query parameter of the next request.

Campaign Report Data

To fetch report data for a single campaign, use the campaign report endpoint:

GET /ads/v3/campaigns/:uuid/report

You can either construct this URI using a campaign ID or use the reportUrl from the campaign listing API as-is.

The response JSON includes a results object at the top level:

{
  "results": {
    "<appslug>": {
      "<platform>": { ... }
    },
    "<appslug2>": { ... },
    ...
  }
}

appslug is a machine readable identifier for the application. Possible platforms are ios, android and html5.

For each platform, an object with the following properties is included:

Note: Properties above are only included when data exists for the type.

Impressions data

The properties of the impressions object are:

Clicks data

The properties of the clicks object are:

Custom data

The properties of the custom object are:

Engagement data

Engagement data combines clicks and custom interactions into overall figures. The properties of the engagement object are:

Daily and hourly breakdowns

Each data object contains breakdowns by day and hour. It's an array containing rows for each time slice.

Example breakdown for daily impressions:

{
  "dailyBreakdown": [
    {
      "impressions": 1234,
      "newUniques": 555,
      "time": "2020-10-06T21:00:00+00:00"
    },
    {
      "impressions": 1432,
      "newUniques": 765,
      "time": "2020-10-07T21:00:00+00:00"
    },
    {
      "impressions": 1111,
      "newUniques": 456,
      "time": "2020-10-08T21:00:00+00:00"
    }
  ]
}

Clicked URL details

The click data contains an array of all clicked URLs in the campaign.

{
  "URLs": [
    {
      "clicks": 123,
      "URL": "https://example.com/url1"
    },
    {
      "clicks": 55,
      "URL": "https://example.com/url2"
    }
  ]
}

Custom interaction details

The custom event data contains an array of all custom interaction events in the campaign. name is an array of strings. It contains arbitrary data unique to the each creative.

{
  "names": [
    {
      "count": 50,
      "name": [
        "scroll"
        "down"
      ]
    },
    {
      "count": 20,
      "name": [
        "tab",
        "news"
      ]
    }
  ]
}

Application Configurations

GET /ads/v2/applications

The applications endpoint returns details of all the application configurations the account credentials used in the request have access to. Note that the field names of the returned objects differ from the ones used by the campaign reports endpoint: