Introduction to FIAM Kits API

Kits API for FIAM Publishers

Your guide to retrieve FIAM core metrics through the Audience Kits API.

Introduction

The Audience Kits API gives you access to create new Kits reports on your account, update Kits reports and to retrieve Kits reporting data for use in your own tools. The API gives you access to your publisher specific data only.

In this document we will go through some FIAM specific use cases to help you pull reporting data for troubleshooting purposes as well as guides on how to retrieve your FIAM core metrics known from the FIAM Toplists.

You find the technical API documentation further down in this document.

If you need help or have any questions, please don’t hesitate to reach out.

Accessing the API

To access the API please create a 'View Only' user with the email from which you intend to use the API. - follow the guide in the User Administration article.

The system will then send you an invitation email from where you can create your password.

Your new email and password combination will be needed to obtain your token for API access. 

To obtain the token simply use the sign-in flow with your email+password combination using the request described in the technical documentation.

Glossary

The API documentation contains different identifiers that are unique to you as a Publisher. Below you will find a description of the various identifiers and instructions on how to retrieve and use them.

Important to pay attention to: 

Whenever we refer to Company ID, Media ID or Section ID throughout this document? Please use your publisher specific ID(s) accessible through the API using your credentials. 

Do not use or copy-paste the code from the examples in the technical documentation. It’s for illustration purposes only. Each publisher has a specific set of ID(s).

Company ID - Your account is assigned a publisher specific Company ID. You will find yours listed in the grey box above. It can also be retrieved using the request described in the technical documentation: "Get all companies".

Media ID - Every media created on your account has been assigned a Media ID (mediaId). 

You can retrieve a list of your media and corresponding Media IDs’ using the Get all media request described in the technical documentation "Get all media".

Section ID - Every section created on your account has been assigned a Section ID (sectionId). You can retrieve a list of sections and corresponding Section IDs belonging to a media by using the Get all sections for media request described in the technical documentation "Get all sections for media".

Touchpoint - Touchpoints are used when creating or updating a Kit to specify the media (Media ID) or sections (Section ID) you wish to include in your Kit.To add media you must use "type": "Media" and specify the Media ID. To add sections, you must use "type": "Section" and specify the  Section ID including the Media ID of the media that the section belongs to.

Touchpoints are described in the technical appendix under "Touchpoints".

Reporting logic

The measurement of your media properties happens on multiple levels that you need to be aware of if you wish to retrieve reporting data comparable to what you find in the FIAM Toplist and Demographic Dashboard.

Your media properties are all measured using unique Media- and Section IDs. One Media Title consists of multiple media versions (or media types) that each have their own unique ID. 

For example ‘Newsmedia ABC’ (website), ‘Newsmedia ABC Android App’ and ‘Newsmedia ABC iOS App’ each have their own unique Media ID. Together they make up ‘Media Site ABC’. 

The same goes for sections: The ‘News’ section on your website will have a unique Section ID and so will the ‘News’ section on your native iOS Application etc. Together they make up one Section belonging to a Media Site.

For reporting purposes this means that there are a couple of best practice rules to keep in mind if what you wish to achieve is reporting comparable to what you see in the Toplist and Demographic dashboards.

1. Create one Kit per Media Title and one Kit per Section - for reporting on all your media properties you must create as many Kits as you have Media Title and Sections.
   
   E.g. if you have two Media Title: one without sections and one with three sections, you must create five (2 media + 3 section) Kits in total. Each Kit can then consist of 1-4 IDs (one for each of the following: Website, iOS App, Android App, Digital Edition)
2. Media level reporting - Whenever you wish to create a Kit on media level, you should not include any sections or Section IDs. When defining your touchpoints use  "type": "Media"
3. Section level reporting - If what you want instead is Section level Kits, make sure to use "type": "Section" when defining your touchpoints by adding the Section ID and the Media ID of the media that your section belongs to.

Make sure not to include any "type": "Media"  touchpoints in that same Kit.

FIAM use cases

Troubleshooting during implementation

You recently changed your implementation and would like to know how the changes have affected the measurement.

You can create per media and section reporting for the current week including the core report metrics: in country pageviews, reach, frequency and session for all media and sections. Note that setting an end date to the end of the current week will initiate the Kits report to be updated on an hourly basis.

1. Get a list of all Media and corresponding Media IDs on your account using the Get all media request described in the technical documentation.
   
   
2. Get a list of all Sections and corresponding Section IDs for your media by using the Get all sections for media request described in the technical documentation.
3. Build one Kit that contains all Media IDs on your account. Use the request described in the technical documentation in "Create Audience Kit". Set a date in the current week.
   Note that the target group should include all - see definitions in the technical documentation "Target group".
4. Build one Kit that contains all Section IDs on your account. Use the request described in the technical documentation: Create Audience Kit. Set a date in the current week.
5. Get report items by using the all media report request described in the technical documentation "All Media overview report"

Toplist reporting metrics

You want to use FIAM Toplist metrics for internal reporting and hence need to be able to create reports including in country-pageviews, reach, sessions and frequency on Section level, Media Site level, Brand (network) level and on Publisher Group (publisher account/ company) level.

1. (To get a list of media, sections and their corresponding Media IDs and Section IDs repeat step 1 and 2 in the previous example.)
2. Build the Kits described below - Use the request described in the technical documentation "Create Audience Kit". Note that the target group should include all.
3. Build a Kit per Media Site (one Kit for each Media Site) that you have on your account. Each Kit should contain the Media IDs corresponding to all (1-4) media types that make up your Media Site. Make sure not to mix media and sections.
4. Build a Kit per Section (one Kit for each Section) that you have on your account. Each Kit should contain the Section IDs corresponding to all (1-4) section types that make up your Section.
5. Build a Kit per Brand (Network) by including all Media IDs belonging to the Media Sites that are part of your Brand.
6. Build one Kit containing all Media IDs on your account to get Publisher Group level reporting.
7. Get report items aggregated across all touchpoints in the Kit by using the total report request described in the technical documentation "Total report".

Demographic dashboard reporting metrics

You want to use the API for internal reporting in your most common demographic target groups and hence need to be able to create Kits reports including frequency and pageviews, reach, hit rate and affinity etc. in target group.

1. Repeat all steps in the above Toplist reporting metrics guide, but make sure to define your target group for all Kits. Use the request described in the technical documentation" "Target group" to set your target group.
2. Get report items aggregated across all touchpoints in the Kit by using the total report request described in the technical documentation: Total report.

FAQ

1. Can I access other publishers data?

No. Only your own publisher data is accessible to you through the Kits API. For competitor data we refer to the public Toplist and the Kits Explorer.

1. Can I create daily reach reports?

No. Daily reach will be delivered as a separate project not currently accessible through the API. You can create reports for less than one week if that is the current week, but the reach figures in Kits are always estimated over the course of a week.

1. Can I get data for the current week?

Yes. While the UserReport interface will only allow you to select weeks in the past, the API let’s you select a date in the current week. Note that setting an end date to the end of the current week will initiate the Kits report to be updated on an hourly basis.

Technical API documentation

Authorization

To obtain token use sign-in flow with email+password combination. 

Request:

Response:

This response returns an idToken that should be passed in the Authorization header. Example:

Note that the id token expires in 1 hour. The refreshToken can be exchanged for new one:

Request:

Response:

Get all companies

All kits are assigned to an account (aka “company”). To get the companies you have access to use this endpoint:

Request: 

Response:

The id of company is used in all endpoints below and referred as companyId

Get all media

Request:

Response:

8.4 Get all sections for media

Sections for certain media can be listed with:

Request:

Response:

Get Audience Kits

To get the list of kits for certain company use the following endpoint:

Request:

Response: 

Create Audience Kit

To create kits for your company, please use corresponding endpoint:

Request:

Pretty-printed payload:

Response:

Kit ID returned in response can be used for subsequent PATCH/GET requests for this kit.

Start date and end date are covering the kit time period in full weeks less than 90 days (12 weeks) in total, so start date is a date in the past and must always be Monday and end date - Sunday.

Target Group

Target group is defined on creation or update 

• gender - target group gender:

1 - male

2 - female

• age - target group age range between 16 and 75
• children - any children in household:

1 - yes

2 - no

• income - target group income:

1 - <200.000

2 - 200.000-400.000

3 - 400.000-750.000

4 - 750.000-1.000.000

5 - 1.000.000+

• education - target group education:

1 - Primary school

2 - High school

3 - Secondary: technical/vocational

4 - Secondary: university-preparatory

5 - University or College

• employment - target group employment status:

1 - Employed

2 - Currently unemployed

3 - Retired, pensioner

4 - Homemaker

5 - Student

6 - Other

• householdSize - target group household size:

1 - 1

2 - 2

3 - 3

4 - 4

5 - 5+

Touchpoints

Touchpoints correspond to certain media and sections. 

Medias can be listed using

Sections for certain media can be listed with:

Touchpoints can be assigned to kit on creation or update:

Update Audience Kit

Kit Reports

To get the insight on your audience kit performance use following endpoints:

All media overview report

This returns a report with a drilldown per media or section. 

Request:

Response:

Total report

This returns an aggregated report across all touchpoints in your Kit. 

Request:

Response:

Current report

This returns a report with seperate drilldown for touchpoints, devices and weeks. It also contains affinity and session information.

Request:

Current report contains: 

• drilldown for touchpoints

• drilldown for devices

• totals distribution by week

• affinities information

• details for number of sessions

References

1. Swagger for authorization methods
2. Swagger for Core API to get company and media information
3. Swagger for AudienceKit API