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 Online Editors generated documents
  • Visits of Europass portal and EWA Editors (combined)
  • Europass portal document downloads
dating back to 2005.
It is HTTP-based and can return results in JSON or CSV format.

How to use

In order 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 EWA Editors generated documents
visits prefix for querying Europass portal + EWA Editors visits
downloads prefix for querying Europass portal documents downloads

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 EWA Editors document type
  • CV
  • ESP
  • LP
  • CL
  • ECV_ESP
country user’s country of residence <2 char country code> eg. IT, PT
date document’s date creation
  • 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 document’s language eg. it_IT, pt_PT
mlanguage user’s mother language eg. Italian, Portuguese
olanguage user’s other languages eg. English
nationality user’s nationality <2 char country code> eg. IT, PT
age user’s age , eg.35 -, eg. 31-35
gender user’s gender
  • male
  • female
  • other
work-experience user’s work experience years eg. 2 -, eg. 0-2

For the Downloads prefix (Europass documents downloads):

NAME DESCRIPTION VALUES
document Europass portal document type
  • ECS
  • EM
  • ECV
  • ELP
  • EDS
document-format Europass portal document format
  • examples
  • template
  • instructions
country document country/ language <2 char country code> eg. IT, PT
language document language <2 char locale code>eg. IT, PT
date date 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

Availiable 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

Availiable Special Parameters:

NAME DESCRIPTION EXAMPLE BOUND TO
groupby group results by param selected groupby=country
orderby show results by acseding (ASC) or descending (DESC) order orderby=date.DESC
top show top N parameter values for grouped by parameter top=15 groupby

Specialised usage of parameters

Parameters, when 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 date parameter 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

The following table demonstrates the response information of Statistics API in a case of an error.

Code Status Occurence Workaround
200 OK Success, return query results -
400 Bad request Failure, occurs when there is a syntax error in the query Revise query syntax and rewrite the query correctly
413 Request Entity Too Large Failure, occurs when the results are too many to be sent Revise query and provide more specific parameters and conditions to narrow the results
500 Internal Server Error Failure, occurs for any non-catchable internal errors of the service Try again

Error response Example:

{
  "error" : {
    "code" : 400,
    "status" : "bad-request",
    "message" : "Validation of query request failed",
    "cause" : "Query parameter parameter name is invalid."
  }
}

Usage examples

Example 1: Get all CV and ECV_ESP documents that were generated during 2017 by citizens residing in Italy ordered by date ascending

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 that were generated in 2017 in Italian ordered by date ascending

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 that were generated during 2017 by Italian citizens ordered by date ascending

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 that were generated during 2017 by Italian native speakers ordered by date ascending

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 online CV 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 during 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