Generate a Report

  1. Endpoint and Metadata
  2. Querying Data
  3. Request Customization
  4. API Exceptions and Error Codes
  5. Limits and Quotas on API Requests

The reporting API enables a client to retrieve the main performance metrics for the past periods. The minimum available date is 6 months ago, the maximum available date is yesterday.

Endpoint and Metadata

The endpoint for requesting reports is:

https://api.yoc.com/api/v1/reporting/publishers

This endpoint also contains the metadata to inform you about all available dimensions and metrics that can be obtained. The metadata is provided if the client is calling the endpoint via GET.

Request Example
curl --request GET \
  --url https://api.yoc.com/api/v1/reporting/publishers \
  --header 'Authorization: Bearer your-access-token'

The response contains all possible columns together with data types and divided into two main categories:

  • group_by: these columns are used for aggregation
  • data_fields: regular metrics
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Fri, 29 Oct 2021 09:53:44 GMT
{
  "modifications": {
    "group_by": [
      {
        "name": "date",
        "type": "DATE"
      },
      {
        "name": " ad_unit_name",
        "type": "STRING"
      },
          ],
    "data_fields": [
      {
        "name": "total_traffic",
        "type": "INTEGER"
      },
      {
        "name": "ad_requests",
        "type": "INTEGER"
      }
    ]
  }
}

A detailed list of aggregation fields and metrics can also be found in the annex.

Querying Data

To retrieve the data a client should submit a POST request to the URL

https://api.yoc.com/api/v1/reporting/publishers

Some filters will be automatically added according to the client permissions.

Request Example
curl --request POST \
  --url https://api.yoc.com/api/v1/reporting/publishers \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"query": {
		"gte": {
			"date": "2021-09-01"
		}
	}
}'
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Fri, 29 Oct 2021 09:53:44 GMT
{
  "request": {
    "query": {
      "and": [
        {
          "and": [
            {
              "gte": {
                "date": "2021-09-01"
              }
            }
          ]
        },
        {
          "in": {
            "company_id": [
              401
            ]
          }
        },
        {
          "eq": {
            "sap_publisher_account_id": 5000000
          }
        }
      ]
    },
    "page_size": 25,
    "page": 1,
    "sort": [],
    "group_by": [
      "company_name"
    ],
    "data_fields": [
      "impressions",
      "views",
      "vtr",
      "clicks",
      "ctr",
      "cpm_EUR",
      "billable_events"
    ]
  },
  "report": {
    "items": [
      {
        "company_name": "YOC Central Eastern Europe GmbH",
        "impressions": 2464559,
        "views": 942895,
        "vtr": 23.03,
        "clicks": 12188,
        "ctr": 10.27,
        "cpm_EUR": 5.21,
        "billable_events": 2224276
      }
    ],
    "report_totals": [
      {
        "impressions": 2464559,
        "views": 942895,
        "vtr": 23.03,
        "clicks": 12188,
        "ctr": 10.27,
        "cpm_EUR": 5.21,
        "billable_events": 2224276
      }
    ],
    "total_items": 1
  }
}

The response body contains an actual query that was used (after applying default parameters and limitations) and the result report:

  • items: data rows
  • report_totals: overall totals in the result data set, ignoring pagination
  • total_items: the total number of rows in the result data set

Request Customization

The request body can contain properties: query, page, page_size, sort, group_by, and data_fields.

For more advanced reportings, please check the next section.

API Exceptions and Error Codes

If an exception appears, the server returns JSON response with a corresponding HTTP status code and a message.

Status Code Description
400 The request was invalid or cannot be served. The exact error is in the error payload
401 Authentication failed, for help please check the section on how to generate your access token
403 The server understood the request, but is refusing it or the access is not allowed
404 There is no resource behind the URI
429 Request is rejected due to rate limiting
500 A generic error message, given when an unexpected condition was encountered . Please try again later.
Example Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-cache, private

{
  "error": "query.ValidationException",
  "message": "Property `site_id` is not sortable.",
  "children": [
    {
      "error": "common.FieldValidationException",
      "message": "Property `site_id` is not sortable.",
      "field": "sort"
    }
  ]
}

Limits and Quotas on API Requests

You can make up to 1200 requests per hour and if you are experiencing rate limit errors, please wait 60 minutes before submitting any more API calls.

The quota may be subject to change

Updated on 01 Nov 2021