XML download¶

Service scope¶

The XML Download service provides measured values on an hourly and daily basis and aggregated to time periods by date. Smaller time units (e.g. real-time data) are not available.

Order / Commissioning¶

The XML Download service is ordered via the INFOnline Order Center at https://kundencenter.infonline.de/#module/ordercenter.

INFOnline then verifies whether there are technical reasons in the measurement system that prevent activation of the service for your digital offering. The ordering party will be informed of this.

Provision¶

After verification of the order, the service for your digital offering is activated in the measurement system. Access to the web portal is protected via authentication.

You will receive the access data as well as the required URL with the setup confirmation by mail. A separate login is created for each digital offer.

Processing time¶

The set-up process (verification and activation) usually takes three working days.

If there are any queries or similar at any point during this process, the INFOnline Customer Service Team will contact you for clarification.

Data availability¶

• Hourly data ("aggr=hour") can be retrieved a maximum of 3 days back.
• Daily data ("aggr=day") can be retrieved for 179 days.
• A maximum of 7 days' worth of consecutive data can be requested.

If data is requested that falls outside of these restrictions, the last existing record will be output.

Runtime¶

The service term applies from confirmation by INFOnline until termination of the service or termination of the metering contract for the corresponding digital offering.

Termination¶

The notice period is always 4 weeks to the end of the quarter.

It is sufficient to send an e-mail with the reason for termination to the following address: service@infonline.de.

If you cancel the metering of the digital offer, the service will automatically expire.

Costs¶

For the XML-Download service there is a one-time setup fee per digital offer of 100 € (net plus the currently valid VAT). There are no ongoing costs.

Invoicing takes place after the service has been set up for your digital offer.

Technical information¶

Data interface¶

Access to the measurement data of the digital offer is realized via a web portal with the URL https://xml.ioam.de/xml.php. The data is accessed via download after HTTP authentication, the data transfer is encrypted via SSL.

Each digital offer registered by you needs a separate access to the XML download.

The measurement data are available in UTF-8 encoded XML text files without BOM (Byte Order Mark).

Naming scheme of the XML files¶

The naming schemes of the possible data aggregations for manual download are explained below.

Hourly data¶

This XML file contains the aggregation data on an hourly basis at the specified time.

1

<Offer identifier>-hour-<Start time of aggregation in UTC (timestamp)>-<End time of aggregation in UTC (timestamp)>.

Hourly data represents the smallest period of observation available and should be considered preliminary. **Real-time data is not provided.

Daily data¶

This XML file contains the aggregation data on a daily basis in the specified time period.

1

<quote identifier>-day-<start time of aggregation in UTC (timestamp)>-<end time of aggregation in UTC (timestamp)>.

This data is only available after two days, as it is first finally aggregated before being made available. Further restrictions in the availability of the measurement data in the XML download can be found in chapter 2.4 Availability of data.

XML download parameters¶

The retrieval of the measurement data via the XML download can be customized by various parameters. These refer to the aggregation type hour/day as well as the time period in which the data is listed in the XML file. Please refer to chapter 2.4 Data availability for the different restrictions on the output of the data.

The following parameters can be added to the URL "https://xml.ioam.de/xml.php" using the "?" character (for the first parameter) and thus define the content of the XML file. Each additional parameter must be appended by a "&" character.

• date - date of the query period, alternatively use {start&end}.
• start - start date of the query period, can be used only in conjunction with {end}.
• end - end date of the query period, can be used only in conjunction with {start}.
• aggr - aggregation of the query, only hour {hour} or day {day} possible

If individual parameters are not set, the XML file is delivered with default values. See the parameter description below for more details.

date parameter¶

The {date} parameter is used to restrict the available measurement data to a specific date. In the following example, an excerpt of the output of the date parameter is shown in addition to the URL.

1

https://xml.ioam.de/xml.php?date=2017-09-01&aggr=day 

1

https://xml.ioam.de/xml.php?date=2017-09-01-15:00&aggr=hour 

Example output can be seen in chapter 2.6 Examples XML download.

start&end parameters¶

The {start} and {end} parameters can be usefully used only in combination and, unlike the {date} parameter, restrict a time period. The parameters "start&end" can be used with the aggregation "day" as well as with the aggregation "hour". The so requested measured values are subject to the rules for the availability of the data (chapter 2.4 Availability of the data).

{start} = start date of the query values {End} = End date of the query values

1

https://xml.ioam.de/xml.php?start=2017-09-01&end=2017-09-05&aggr=day 

The period of the output can also be extended by the specification of a time, in order to get a concrete period delivered to the hour. However, this restriction can only be used in combination with the data aggregation "hour".

1

https://xml.ioam.de/xml.php?start=2017-09-04-12:00&end=2017-09-05-13:00&aggr=hour 

Please pay attention to the respective restrictions of data availability in "Chapter 2.4 Availability of data".

Data availability¶

The data in the XML download can be retrieved dynamically. However, this retrieval is subject to certain availabilities, so that the time-exactly determined data are available performantly.

???+ important "Important

1

All time data in the XML files are in UTC.

Hourly data: "aggr=hour ".

Data on an hourly basis can be retrieved three days in arrears. If data outside of these availability rules is requested, one of the error messages listed below will be issued.

Daily data: "aggr=day "

Data on a daily basis is retrospectively retrievable for 179 days. Aggregation of daily data is only possible two days retrospectively to the current date (e.g. on 06.10. the daily data from 04.10. are available)! Data can be requested for a maximum of seven consecutive days. If a longer period is selected, one of the error messages listed below will be displayed.

Error messages¶

• Error messages for invalid period "..." If data is not available due to the selection of an invalid period, the following values may occur within the dimension:

• unkown error

• date(XXX) too old
• start(XXX) greater than end(XXX)
• start(XXX) older than max. allowed value (XXX)
• start(XXX) too old
• too much days (XXX/YYY)
• end(XXX) too young

Example output for the error message "start(XXX) greater than end(XXX) "

1
2
3

<error>
  start(2017-10-24-10:00) greater than end start(2017-10-06-10:00)
</error>

• Error messages in case of unavailable data If data cannot be made available for other reasons, the value "missing data" is output in the individual dimensions of the different measurement values (2.5.2 Measurement data types in the XML file) in the XML document.

???+ note "Note

1
2
3

- Please note that hourly data may be preliminary data. They are not necessarily the final measurement data.
- Daily data are available only in aggregated state. (Current date + 2 days) 
- A direct comparison of hourly and daily data is only possible to a limited extent.

Description of XML data¶

Description of the data formats¶

The requested data in the XML file contains various measurement data and information of a digital offer. This data is output for the specified time period and data aggregation. The form of the output is thereby kept uniform within the root node ... and is structured as follows:

1
2
3
4
5
6

<dim_measurement_datatype date="YYYY-MM-DD HH:MM" aggr="day"|"hour">
[<aggregation category>ABC</aggregation category>]
<Measurement data count total>X</measurement data total>.
[<measurement data number domestic>Y</measurement data domestic>]
[<measurement data number foreign>Z</measurement data foreign>]
</dim_measurement_data_type>

...

This element node specifies the data type of the measurement data within this node.

The following measurement data types are available:

• Agents
• clients
• PIs (per code)
• Sessions
• URLs

date="YYYY-MM-DD HH:MM "

The {date} attribute specifies the time of the measurement data specified within the node. If the data is requested on an hourly basis, "00:00:00" is always output as the time.

aggr= "day" | "hour "

The {aggr} attribute specifies the aggregation of the data within the node. The aggregation depends on the request for the data via the URL and is identical for all measurement data types in the XML file.

....

This element is only available for measurement data types that are aggregated by another category in addition to a count (for example, "PIs per code"). The category name is individual depending on the aggregation feature (example: ... ).

[...]

The measurement data count is output in the form of three values: The total value for the node, and individual values for "domestic" and "foreign". The naming of the sub-element is based on the measurement data type. The following example is obtained for the sessions of one day:

1
2
3

<sessions>63526</sessions> (total number)
<sessionsinland>53061</sessionsinland>
<sessionsforeign>10465</sessionsforeign> 

Measurement data types in the XML file.¶

The requested XML file contains basically the identical measurement data types. If there are no values for the selected aggregation period, these nodes are listed without values. Example (no Errors present):

The available measurement data types are described in more detail below.

Agents - number of visits per browser type¶

This measurement data type outputs the number of visits per dedicated browser type in the selected aggregation period.

Example:

1
2
3
4
5
6

<dim_agents date="2017-09-20 00:00:00" aggr="day"> 
        <agent>Chrome (Android)</agent>
        <sessions>2348</sessions>
        <sessionsinland>2005</sessionsinland> 
        <sessionsforeign>343</sessionsforeign> 
</dim_agents>  

**Reference.

A separate node is created for each browser type per requested time period.

Possible aggregation:

Hourly and daily values

Error - Hits per error code¶

This measurement data type contains the hits that occur in the aggregation period on a dedicated error code type. A large proportion of the hits listed here are not PI-relevant and can only be requested for hourly data.

Example:

1
2
3
4

<dim_errors date="2017-09-20 19:00" aggr="hour">
         <error>A1</error>
         <hits>1</hits> 
<dim_errors> 

Reference:

One node is created per error code for the requested aggregation period.

**Possible aggregation.

Hourly values

Events - Actions per event type¶

This measurement data type outputs the number of actions in the aggregation period that occur on a dedicated event type. The measurement data type is populated for apps only. Some of the actions counted are not PI relevant. For web and MEW offers, this is basically empty.

Example:

1
2
3
4
5
6

<dim_events date="2017-09-12 00:00:00 "aggr="day">
         <event>application-enterforeground</event>
         <hits>42</hits>
         <hitsinland>40</hitsinland>
         <hitsforeign>2</hitsforeign>
</dim_events>  

Reference:

For each event type with counted actions, a separate node is listed per aggregation period.

**Possible aggregation.

Hourly and daily values

PIs - PIs per code¶

This measurement data type outputs the PIs for the requested aggregation period per dedicated code.

Example:

1
2
3
4
5
6

<dim_pis date="2017-09-20 00:00:00" aggr="day"> 
        <code>code123456</code> 
        <pis>35</pis> 
        <pisinland>29</pisinland>
        <pisland>6</pisland> 
</dim_pis>

Reference:

A separate node is created for each code per period.

**Possible aggregation.

Hours and daily values

Sessions - number of visits¶

This measurement data type outputs the total number of visits for the requested aggregation period.

Example:

1
2
3
4
5

<dim_sessions date="2017-09-20 00:00:00" aggr="day">
       <sessions>63526</sessions>
       <sessionsinland>53061</sessionsinland> 
       <sessionsforeign>10465</sessionsforeign> 
</dim_sessions> 

Reference:

A separate node is created per requested aggregation period.

**Possible aggregation.

Hours and daily values

URLs - number of hits per URL¶

This measurement data type outputs the number of PIs per URL that received traffic during the aggregation period. The counted hits are PI relevant and can be considered as full PIs.

Example:

1
2
3
4
5
6

<dim_urls date="2016-04-12 00:00:00" aggr="hour"> 
       <url>www.infonline.de</url>
       <hits>21</hits>
       <hitsinland>20</hitsinland> 
       <hitsforeign>1</hitsforeign> 
</dim_urls>

Reference:

One separate node is created per URL visited in the aggregation time interval.

**Possible aggregation.

Hours and daily values

Error codes¶

The following table describes the error codes that can occur in the "Number of hits per error code type" measurement data element:

Example XML download¶

Example (period):

https://xml.ioam.de/xml.php?start=2017-05-07&end=2017-05-12&aggr=day

Extract from XML file:

Example (Date with daily data):

https://xml.ioam.de/xml.php?date=2017-12-12&aggr=day

Extract from the XML file:

Example (Aggregation hour with time):

https://xml.ioam.de/xml.php?date=2017-12-12&aggr=day

Extract from the XML file: