INFOnline Reporting API¶
Service Description v2.0 | 02.06.2023
Scope of service¶
The INFOnline Reporting API service can be used to query measured values on an hourly, daily and monthly basis. Depending on the measured value, both preliminary and final aggregated data can be requested. All data available at the time of the query are available for each measured value, for many values (e.g. page impressions) also almost real-time data.
Via the INFOnline Reporting API you can retrieve the measured values for all sites that you have registered for measurement with INFOnline via your customer account / customer number. You regularly receive 1 API key per customer account for the retrieval. Additional keys can be booked.
Subject to the approval of the respective site owner, the service can also be provided across accounts - i.e. with access to sites from different customer accounts. The approval of the site needs to be sent in advance by e-mail to: firstname.lastname@example.org. INFOnline regularly provides the named contact person with 1 API key for cross-account data retrieval. Additional keys can be booked.
In addition, the output format of the API can be selected by your technician. A specific booking of one of the output formats is not necessary. The following formats are available:
- JSON (default)
- CSV Headless
The technical documentation according to OAS3 is provided online. Further information can be found in the chapter Technical Documentation.
Adaptations and changes to this service are possible at any time by INFOnline. Adjustments will be communicated in good time in advance by INFOnline by e-mail.
Order / Commissioning¶
The ordering of the INFOnline Reporting API service is carried out via the INFOnline Customer Center. In the order form the ordering party submits the details for order processing (ordering party / invoice recipient, site Ids, measurement methods, metrics, aggregation levels, recipient API invitation). The client receives a confirmation of receipt. INFOnline verifies whether all necessary information for the provision of the service is available. If this is the case, the client receives an order confirmation by e-mail within 3 working days. If information is still missing, INFOnline will also contact the client by e-mail. The duration of order processing may vary depending on the scope of the order and any necessary approvals.
Attention: Activation of the service "XML-Download for your site Ids"
Activation of the "INFOnline Reporting API" service by INFOnline regularly leads to termination and deactivation of the XML Download service for all booked site identifiers for customers who already use the XML Download: With the dispatch of the order confirmation by INFOnline, the termination of the 'XML Download' service will then take effect on 30th June 2023, and INFOnline will deactivate the service in the system.
Ordering additional API Keys¶
When booking the INFOnline Reporting API service, one API Key per customer is included. In case you require further keys with identical or different access authorisation, you can order additional keys via the order form in the INFOnline Customer Center.
After checking the order, the service with the selected access authorisation for the data retrieval of your sites will be activated by INFOnline within 3 working days and a temporary access to your API Key for the INFOnline Reporting API will be sent by e-mail to the named contact person.
This API Key is used to authenticate your requests to the INFOnline Reporting API and must be kept and used by you in a protected manner. The API Key is only displayed to you temporarily via an invitation link on a website. From there, you must save the API Key manually. As soon as the browser tab is closed, the API Key cannot be displayed again.
Provision of further API Keys¶
Several API Keys can be ordered per customer, depending on the scope of services you wish to access with the Key. The provision takes place in the same way as the initial provision of the API Key included in the basic scope, via the order form in the INFOnline Customer Center.
Changes to existing API Keys¶
The API Key generated for you contains special authorisations for the use case booked by you at the time of provision. If changes are made, for example by cancelling sites or booking INFOnline Measurement for further sites (site Ids), a new API Key must be generated and exchanged on your side. Order the new API Key via the order form in the INFOnline Customer Center.
INFOnline verifies whether all necessary information for the provision of the API Key is available. If this is the case, the ordering party will receive an order confirmation by e-mail within 3 working days. If information is still missing, INFOnline will also contact the principal.
The duration of the implementation may vary depending on the number and scope of the changes as well as any necessary approvals. Possible changes to an API Key are:
- Addition or removal of site Ids
- Change of authorisations (access to further aggregations or measured values)
The duration of the set-up is usually three working days. The duration of the set-up can also vary depending on the number of API Keys, scope and metrics, as well as any approvals that may be required. If there are any queries or delays at any point, the INFOnline Customer Service Team will contact you by e-mail.
The service term is 12 months from confirmation or order acceptance by INFOnline until termination of the service or until termination of the main contract for measurement for the sites of the associated customer account(s). If the service contract is not terminated by an authorised contact within the notice period, the contract term shall always be automatically extended by a further 12 months.
The cancellation period is 4 weeks to the current end of the term.
To terminate the contract, please send an e-mail with the reason for termination to the following address: email@example.com.
Provided that you cancel the metering of all your sites, the service will automatically expire on the day the cancellation of the metering contract comes into effect.
All prices quoted are net plus the currently applicable statutory VAT. For the INFOnline Reporting API service, a one-off set-up fee of €99.90 is charged per customer.
The monthly fees amount to €24.90. The basic fee includes 800 API calls on a daily average per month. The assessment basis for the amount of the monthly basic fee is solely the number of monthly API calls. The API calls are calculated per customer account.
If the contingent of 800 API calls per customer on a daily average per month included in the basic fee is exceeded, additional monthly costs of 4.90 euros per 800 additional API calls on a daily average per month will be incurred.
INFOnline will provide the client with additional or new API Keys (e.g., in the event of cancellation or registration of sites) free of charge for the reporting API access of its customer account.
Invoicing takes place monthly after the service has been provided. The invoice shall be sent as a PDF by e-mail from the address 'firstname.lastname@example.org' to the Client's billing office. (see also regulations on sending invoices in current INFOnline price list).
The day limit per customer is 10,000 API calls. If you need a higher daily limit, please indicate this in your order or contact us by mail: email@example.com
What exactly is an API call?
An API call is defined as a request for data via the INFOnline Reporting API (REST API) via HTTP GET request. Per request, one category of measured values (e.g. visits) can be queried for a site Id in an aggregation level for a specific date. The API calls are determined per customer account.
Examples: | Use Case | Required API Calls | | ------ | ------ | | Visits and PIs of the previous day for 2 site Ids | Two queries per site Id = 4 API calls | | Qualified Clients, PIs, PIs per code and Visits of the previous month for 1 site Id | 4 queries per site Id = 4 API calls |
Cost table monthly costs¶
For orientation, the monthly costs per API call contingent are described below. The API calls are the daily average per month. If you need the monthly value for your calculations, the value listed below must be multiplied by the days of the months.
|API calls per customer number (daily average per month)||Monthly costs in €|
|801 - 1.600||29,80|
|1.601 - 2.400||34,70|
|2.401 - 3.200||39,60|
|3.201 - 4.000||44,50|
|4.001 - 4.800||49,40|
|4.801 - 5.600||54,30|
|5.601 - 6.400||59,20|
|6.401 - 7.200||64,10|
|7.201 - 8.000||69,00|
|8.001 - 8.800||73,90|
|8.801 - 9.600||78,80|
|9.601 - 10.000*||83,70|
*A maximum of 10,000 API calls are possible per day per customer account by default.
Examples of monthly costs
- Included in basic fee: 800 API calls * 30 days = 24,000 API calls in April = €24.90 plus VAT.
- up to 48,000 API calls in April (daily average per month: 1,600) = €24.90 + €4.90 = €29.80 plus VAT.
- Included in basic fee: 800 API calls * 28 days = 22,400 API calls in February= 24.90 € plus VAT.
- up to 67,200 API calls in February (daily average per month: 2,400) = €24.90 + €4.90 + €4.90 = €34.70 plus VAT.
The data are available in different aggregation levels. Please note that some values per aggregation level have an independent metric that cannot be generated based on the calculation of previous aggregation levels.
Example: Aggregation levels of the Clients metric
The measurement of clients per site Id forms a standalone metric at each of the aggregation levels.
- Clients (hour): How many unique clients visited the offer in the given hour?
- Clients (day): How many unique clients visited the offer on the given day?
- Clients (month): How many unique clients visited the offer in that month?
A client visiting the site every day in January at 9am, 12pm and 6pm is reflected in the aggregation levels as follows:
- Hour: 3 hour clients per day
- Day: 1 day client per day
- Month: 1 monthly client
The following aggregation levels are available:
|Aggregation||Availability||Query Period||Preliminary Data?|
||max. 180 days retrospective||Query per day||Different for each metric|
||max. 180 days retrospectively||query per day||Different for each metric|
||retrospective if available||query per month||different for each metric|
Preliminary data are marked with the flag 'preliminary: true'.
If data is requested that falls outside of these restrictions, an error message will be issued.
INFOnline uses several measurement procedures to measure and create metrics, which are brought together under our INFOnline Measurement. Different metrics are available depending on the measurement procedure.
- INFOnline Measurement (for values see IDAS tab INFOnline Measurement)
- INFOnline pseudonym (for values see IDAS tab Pseudonym), consent-bound determination of client-related metrics
- Census measurement (for values see IDAS tab Census), consent-free determination of page impressions
By default, all available values from the individual procedures are transmitted when a metric is queried. If you require a restriction to one or more measurement methods for your queries, please let us know by email: firstname.lastname@example.org
- Page impressions (PIs)
- PIs per code (only for census measurement & INFOnline pseudonym)
- PIs per URL (only for census measurement & INFOnline pseudonym)
- Visits (only for INFOnline Measurement & INFOnline pseudonym)
- Clients (only for INFOnline pseudonym)
- Qualified Clients (only for INFOnline Measurement)
All time information is in UTC.
Depending on the metric and measurement procedure, a domestic and international value is transmitted in addition to the total value of the metric.
Depending on the metric and measurement procedure, a flag for preliminary data is also transmitted (
"preliminary": true or false). Final data will only be available after 2 days.
Each query contains metadata in addition to the measured values.
|site||Requested site ID||"foo"|
|exported_at||Time of query||"2022-12-30T12:00:58"|
|version||version number data schema||"1"|
Access to the measurement data of your sites is realised via a REST API. Depending on the order, you can query the measured values of all sites that are active under your customer number with only one API key.
The queries are made via an HTTP GET request. Authorisation is required to access the data.
Authorization takes place via the individually generated API Key. The API Key must be stored in the header of the request under 'authorization'. Depending on the booking, the API Key only contains an authorisation for the query of individual measurement procedures, metrics, aggregation levels or site Ids.
The HTTP GET request must/may contain the following parameters. The parameters are connected by a
|site||site Id||authorized INFOnline site Id||yes||site=foo|
|aggregation||aggregation level||'HOUR, DAY, MONTH'||yes||aggregation=DAY|
|date||date in format
|returntype||returned data format||
- Page impressions:
- Qualified Clients:
returntype can be used to select from one of four different data formats for the queried metrics. These data formats are available:
- JSON (recommended, default value)
- csv_headless (not recommended)
The fixed column sorts for the data formats
csv_headless are available from version 1.1.1 of the Reporting API. The planned rollout for the update is 15.06.2023.
In order to enable the best possible compatibility of the queries with the data format
csv_headless, there is a fixed column sorting for the data output per API endpoint (metric). The columns are separated by
; (semicolon). The sorting is as follows and applies to all measurement systems:
- Endpoint: pageimpressions
- Endpoint: visits
- Endpoint: qualifiedclients
- Endpoint: pageimpressionspercode
- Endpoint: pageimpressionsperurl
- Endpoint: clients
We reserve the right to make changes to the sorting.
The INFOnline Reporting API is described according to the OAS3 standard (OpenAPI Specifictation Version 3). The description including all retrievable metrics can be found here:
Availability / SLAs¶
|Description||INFOnline provides a REST API via which the client can retrieve defined metrics of its active sites. With an API key and corresponding booked permissions, the values of all sites of a client account can be retrieved. A restriction to individual site Ids is also possible. Depending on the booked authorizations, the INFOnline Reporting API returns measured values for one or more measurement systems. The data can be queried for different aggregation levels. The returned data format can also be selected. All information in the SLAs refers exclusively to the provision of the API. The availability of the data is not part of this agreement.|
|Provision time||24/7, all year round|
|Availability||98% annual average. Downtimes are determined via a monitoring tool from INFOnline.|
|Fault Class & Response Time||Class 1 (highest): complete system failure, response time 60 minutes.
Class 2: operational impairment, response time 1 working day within the INFOnline business hours.
Class 3: minor impairment, response time 2 working days within the INFOnline business hours.
|Maintenance time slot||Regular maintenance is carried out on working days and are announced with appropriate lead time. Urgent maintenance can be announced at short notice with one day's notice. INFOnline reserves the right to change these time periods insofar as this is reasonable for the principal.|
|Handover point||E-mail to email@example.com. The notification shall be deemed to have been handed over as soon as a reply e-mail with ticket ID has been sent by INFOnline to the notifying party.|
|Cooperation obligations of the service recipient||The regulations and notes from the service description must be observed. The queries must be implemented in accordance with the technical documentation. To handle timeouts and other problems during the query, e.g. connection problems, the query logic must be implemented in an appropriately robust manner so that individual timeouts do not lead to problems in the processing chain at the service recipient. Therefore, unsuccessful queries should be repeated. A stable internet connection is a prerequisite.|
|Response times of the API||maximum 60 seconds|