Reporting API

The goal of this document is to show how to use our reporting APIs to retrieve delivery statistics about your DOOH campaigns.

This will go through:

1. Steps to access the API
2. Using the interactive documentation to explore the API
3. Using the main endpoints to retrieve detailed reports
   1. Either in machine(JSON, MSGPACK) or human-readable (CSV, XLS) format
      
      

For the moment only campaigns operated on our RTB platform are available on this reporting API.

The main documentation can be found at https://datahub.displayce.com/agencies/v2/redoc. Alternatively:

1. A swagger interface to query the API interactively: https://datahub.displayce.com/agencies/v2/docs
2. The openAPI json definition at https://datahub.displayce.com/agencies/v2/openapi.json

Authentification

There MUST be a JWT token supplied through the field 'Authorization` in the portion of your request.
You MAY put "bearer" followed by a space before your token as specified by https://www.rfc-editor.org/rfc/rfc6750#section-2.1

Interactive usage

Please be aware that the payloads returned by the API for large campaigns are huge, several MB of compressed json.
Therefore it is not advised to interactively try the full reports or hourly tabular reports from the interactive interface as this will most likely freeze your browser.

Here's a sample session where we will retrieve the list of campaigns, and for a given campaign, its hourly reports.

1. Authenticate and get a JWT token
   
   a. Click on the "/rtb/reports/login" card
   b. Click on try it out
   c. Input your DPS's credentials, username and password
      ⚠️ it is not possible to connect to the API using google SSO ⚠️
   d. Click execute 
   
   Your token will be given in the "Response body" block.
   This field is hidden in the image above for security reasons.
2. Authorise and input your private access key
   
   
   a. Input your token
3. Switch the first endpoint to interactive mode
4. 
5. input the campaign UUID (you can retrieve this UUID on our DSP), then Execute:
6. 
7. This endpoint will return global campaign information
   1. Every returned value is fully documented right after the endpoint interactive form
      1. 
8. This UUID can then be passed to the second endpoint /agencies/v2/rtb/reports/delivery/ to retrieve detailed campaign information:
   1. 

Staging environment

A staging API (with very limited data) is available at https://datahub.dev.displayce.com/agencies/v2/docs Please get in touch with your account manager if you want us to load some realistic data in this staging environment for your tech team.

Accessing your campaigns reporting

This API provides two major endpoint:

• /rtb/campaigns/{agency_id}: allows you to retrieve the set of campaigns associated with your agency; as well as their status (0: pending, 1: running, 2: finished)
• For each of these campaigns, you can retrieve everything related to their setup and reports at /rtb/reports/delivery/{campaign_uuid} ; where campaign UUID is one of the UUID retrieved from the first endpoint.