Statistics API

Overview

The Europass Statistics API is part of the public set of Europass web services.

Europass documents online statistics reports

The Statistics API allows users to query Europass statistical data for

  • Europass documents generated through the online editors
  • Visits to the Europass portal and EWA editors (combined)
  • Downloads from the Europass portal (CV/LP examples, etc.) 

dating back to 2005.

It is HTTP-based and can return results in JSON or CSV format.

How to use

To use the Statistics API, you simply need to send a GET request to https://europass.cedefop.europa.eu/stats-api/to providing the desired response format, a prefix and some parameters.
URL format: https://europass.cedefop.europa.eu/stats-api/to//;

Response format

The Statistics API returns the results or the error message in JSON or CSV format. This is determined by the request endpoint:

ENDPOINT RESPONSE TYPE
/stats-api/to/json JSON
/stats-api/to/csv CSV
/stats-api JSON (default)

Request prefix

The Statistics API returns the results or the error message in JSON or CSV format. This is determined by the request endpoint:

PREFIX NAME RESPONSE DESCRIPTION
generated prefix for querying documents generated through the Europass online editors
visits prefix for querying visits to Europass portal + online editors
downloads prefix for querying downloads from the Europass portal (CV/LP examples, etc.)

Parameters query

The query syntax definition includes:

  • Parameters: used to describe the parameters that take part in the query.
  • Operators: used to query logical comparisons, relations and value ranges related to the parameters.
  • Special parameters: used to organise query results.

Parameters

For the Generated prefix (documents generated online):

NAME RESPONSE DESCRIPTION VALUES
document-type type of document generated through the Europass online editor
  • CV
  • ESP
  • LP
  • CL
  • ECV_ESP
country country of residence of the user <2 char country code> eg. IT, PT
date date of creation of the document
  • YYYY, eg 2017
  • YYYY.MM, eg. 2017.01
  • YYYY.MM.DD, eg. 2017.01.01
  • YYYY-YYYY, eg. 2005-2017
  • YYYY.MM-YYYY.MM, eg. 2017.01-2017.12
  • YYYY.MM,YYYY.MM, eg. 2017.06,2017.12
  • YYYY.MM-YYYY.MM,YYYY.MM-YYYY.MM
language language of the document eg. it_IT, pt_PT
mlanguage mother language of the user eg. Italian, Portuguese
olanguage other languages known by the user eg. English
nationality nationality of the user <2 char country code> eg. IT, PT
age age of the user eg.35 -, eg. 31-35
gender sex of the user
  • male
  • female
  • not specified
work-experience years of work experience of the user eg. 2 -, eg. 0-2

For the Downloads prefix (Europass documents downloads):

NAME DESCRIPTION VALUES
document type of Europass document
  • ECS
  • EM
  • ECV
  • ELP
  • EDS
document-format format of the Europass document
  • examples
  • template
  • instructions
country country/language of the document <2 char country code> eg. IT, PT
language language of the document <2 char locale code>eg. IT, PT
date date on which the document was downloaded
  • YYYY, eg 2017
  • YYYY.MM, eg. 2017.01
  • YYYY.MM.DD, eg. 2017.01.01
  • YYYY-YYYY, eg. 2005-2017
  • YYYY.MM-YYYY.MM, eg. 2017.01-2017.12
  • YYYY.MM,YYYY.MM, eg. 2017.06,2017.12
  • YYYY.MM-YYYY.MM,YYYY.MM-YYYY.MM

Available Operators:

TYPE OPERATOR EXAMPLE LOGICAL DESCRIPTION
Assignment Group = param=value1 param value equals value1
Group , param1=value1,value2,value3 param value applies for values valueA to valueN
Or + param1=value1+value2+value3 param1 value equals value1 OR value2 OR value3
Range - param=value1-valueN param value is between value1 and valueN
Range Group - , … , - param=valueA-valueB, ... ,valueY-valueZ param value belongs to groups values valueA-valueB, ... ,valueX-valueZ

Available Special Parameters:

NAME DESCRIPTION EXAMPLE BOUND TO
groupby group results by parameter selected groupby=country  
orderby show results by acsending (ASC) or descending (DESC) order orderby=date.DESC  
top

Show top N parameter values for ‘grouped by’ parameter.

top=15 groupby

Specialised use of parameters

Parameters used without an operator in the GET request, will return the result of a query that fetches the count number of records containing a not null value of the parameter:

Request:

GET /stats-api/query-prefix;parameter;

Response:

{ parameter : number }

The parameter "date" also has specialised usage depending on the query format as a range. When a date is used as a range the query will group the results by date (from past to present), regardless of other parameters, unless a groupby parameter exists, declaring the parameter used to group the results by.
For example, the following query will return the values that conform to some parameters queries, dated from 2010 to 2013, grouped by date.

Request:

GET /stats-api/query-prefix;parameters queries;date=2010-2013;

Response:

{ "Dataset" : { "id" : "metric", "values" : [ { "value" : [ value, 2010, ... ] }, { "value" : [ value, 2011, ... ] }, { "value" : [ value, 2012, ... ] }, { "value" : [ value, 2013, ... ] } ], "dimensions" : [ { "index" : 0, "id" : "rec_count", "label" : { "some" : true, "none" : false }, "size" : 1, "category" : [ ], "role" : { "some" : true, "none" : false }, "categoriesAsMap" : { "rec_count" : [ ] }, "required" : false, "constant" : true }, { "index" : 1, "id" : "year_no", "label" : { "some" : true, "none" : false }, "size" : 1, "category" : [ ], "role" : { "some" : true, "none" : false }, "categoriesAsMap" : { "year_no" : [ ] }, "required" : false, "constant" : true }, …] } }

When a month value is also present in a date range in a query:

Request:

GET /stats-api/;;date=2013.01-2013.12;

Response:

{ "Dataset" : { "id" : "metric", "values" : [ { "value" : [ value, 2010, 1, ... ] }, { "value" : [ value, 2010, 2, ... ] }, …, { "value" : [ 19862, 2013, 12, ... ] } ], "dimensions" : [ { "index" : 0, "id" : "rec_count", "label" : { "some" : true, "none" : false }, "size" : 1, "category" : [ ], "role" : { "some" : true, "none" : false }, "categoriesAsMap" : { "rec_count" : [ ] }, "required" : false, "constant" : true }, { "index" : 1, "id" : "year_no", "label" : { "some" : true, "none" : false }, "size" : 1, "category" : [ ], "role" : { "some" : true, "none" : false }, "categoriesAsMap" : { "year_no" : [ ] }, "required" : false, "constant" : true }, { "index" : 2, "id" : "month_no", "label" : { "some" : true, "none" : false }, "size" : 1, "category" : [ ], "role" : { "some" : true, "none" : false }, "categoriesAsMap" : { "month_no" : [ ] }, "required" : false, "constant" : true }, ... ] } }

Response codes

Error Response

In case of an unsuccessful request, the response will include an 4xx or 5xx HTTP Status Code and optionally (depending on the HTTP Status) an XML or JSON error object with details about the error. Whether the error object is XML or JSON, depends on the Content-Type header of the request. If Content-Type: application/xml or Content-Type: application/json, the error object will be in XML or JSON format respectively. If the value of Content-Type is set to something different than XML or JSON (e.g. application/pdf) or if the Content-Type header is missing from the request, the error object defaults to XML format.

Regardless of XML or JSON, the error object consist of the following properties:

trace
A unique error id in the form of an 8-character alphanumeric string (e.g. ar37tMkr) used for troubleshooting purposes. This is the reference code to use in case you need to contact the Europass support team.
code
A short, codified representation of the error message such as unsupported.content.type, which can be used e.g. for testing purposes.
message
A human-friendly description of the error at hand.

A list of all possible 4xx and 5xx HTTP Statuses along with a short description for each one of them is given below. The exact error responses to expect for each service are described in detail in the REST API Reference

Errors

HTTP Status Description
400 Bad Request Something is wrong with the input document (it is missing/empty or e.g. invalid XML/JSON) or with the Accept-Language header (the requested locale is not supported by Europass).
403 Forbidden The request was made over plain, non-secure HTTP while HTTPS is required.
404 Not Found The requested resource could not be found, possibly due to a typo (e.g. /to/pdf instead of /document/to/pdf).
405 Method Not Allowed The requested resource does not allow the HTTP Method used (e.g. DELETE instead of POST).
406 Not Acceptable An invalid Accept header was set in the request (e.g. Accept: application/msword instead of Accept: application/pdf when generating a PDF). Note though that normally you should not include at all an Accept header in the request.
415 Unsupported Media Type This error can appear in the following cases:
  • The value of the Content-Type header is missing from the request or it is invalid (e.g. Content-Type: application/xml for a service that consumes JSON only such as /document/to/xml).
  • The input document is missing/empty or its format is not supported by the requested service (e.g. a PDF file was sent to /document/to/pdf).
500 Internal Server Error Something went wrong on the server-side (i.e. most probably it is not your fault). If the problem persists, contact the Europass support team.
503 Service Unavailable The requested service is unavailable most probably due to maintenance reasons. If the problem persists, contact, the Europass support team.

Usage examples

Example 1: Get all CV and ECV_ESP generated in 2017 by citizens residing in Italy by ascending date

Request:

GET /stats-api/to/csv/generated;country=IT;date=2017.01-2017.12;document-type=CV+ECV_ESP;orderby=date.ASC

Response:

rec_count,year_no,month_no,address_country 480673,2017,1,IT 452057,2017,2,IT 491157,2017,3,IT 391690,2017,4,IT 470345,2017,5,IT 400667,2017,6,IT 393786,2017,7,IT 324901,2017,8,IT

Example 2: Get all CV and ECV_ESP documents generated in 2017 in Italian ordered by ascending date

Request:

GET /stats-api/to/csv/generated;date=2017.01-2017.12;document-type=CV+ECV_ESP;language=it_IT;orderby=date.ASC

Response:

CV + ECV_ESP,doc_lang,year_no,month_no 496319,it_IT,2017,1 470049,it_IT,2017,2 500934,it_IT,2017,3 394068,it_IT,2017,4 475087,it_IT,2017,5 417029,it_IT,2017,6 412798,it_IT,2017,7 340897,it_IT,2017,8

Example 3: Get all CV and ECV_ESP documents generated in 2017 by Italian citizens by ascending date

Request:

GET /stats-api/to/csv/generated;date=2017.01-2017.12;document-type=CV+ECV_ESP;nationality=IT;orderby=date.ASC

Response:

rec_count,nationality,year_no,month_no 234360,IT,2017,1 219139,IT,2017,2 238717,IT,2017,3 187971,IT,2017,4 226430,IT,2017,5 192066,IT,2017,6 189151,IT,2017,7 153904,IT,2017,8

Example 4: Get all CV and ECV_ESP documents generated in 2017 by Italian native speakers by ascending date

Request:

GET /stats-api/to/csv/generated;date=2017.01-2017.12;document-type=CV+ECV_ESP;mlanguage=Italian;orderby=date.ASC

Response:

rec_count,m_lang,year_no,month_no 461016,Italian,2017,1 428011,Italian,2017,2 463049,Italian,2017,3 369456,Italian,2017,4 440588,Italian,2017,5 376771,Italian,2017,6 369058,Italian,2017,7 307087,Italian,2017,8

Example 5: Get the years of work experience of Europass CV online users residing in Italy (2017)

Request:

GET /stats-api/to/csv/generated;date=2017;document-type=CV+ECV_ESP;work-experience=0-2,3-5,6-10,11-20,21-100

Response:

SUM(e.upto2),SUM(e.from3to5),SUM(e.from6to10),SUM(e.from11to20),SUM(e.from20plus),year_no 2339422,1951015,1767508,1501129,882257,2017

Example 6: Get the age of Europass CV online users residing in Italy (2017)

Request:

GET /stats-api/to/csv/generated;date=2017;document-type=CV+ECV_ESP;age=0-20,21-25,26-30,31-35,36-100

Response:

SUM(e.upto20),SUM(e.from21to25),SUM(e.from26to30),SUM(e.from31to35),SUM(e.from35plus),year_no 1230371,2152663,1421956,707508,1111361,2017

Example 7: Get all visits from Italy in 2017

Request:

GET /stats-api/to/csv/visits;country=IT;date=2017.01-2017.12;orderby=date.ASC

Response:

volume,year,month,iso_country_code 499039,2017,1,IT 492619,2017,2,IT 528742,2017,3,IT 421128,2017,4,IT 469165,2017,5,IT 395675,2017,6,IT 400432,2017,7,IT 346313,2017,8,IT

Example 8: Get all documents downloaded in Italian in 2017

Request:

GET /stats-api/to/csv/downloads;date=2017.01-2017.12;orderby=date.ASC

Response:

volume,year,month 1271508,2017,1 1140151,2017,2 1204586,2017,3 917432,2017,4 1047697,2017,5 883786,2017,6 864723,2017,7 1025457,2017,8

Was this page helpful?
Let us know how we did