January 30, 2025
API Technical Documentation
Introduction
Do you want to use the data from Mapineq in your own application or website? This API technical documentation provides a complete list of API endpoints and their parameters with simple examples for their usage. In this tutorial, we will submit queries to the Mapineq API endpoints in the form of HTTP GET requests, and we will receieve API responses in JSON format containing the data that we requested.
If you would like an introduction on querying the API from R or Python to retrieve data in the form of data frame objects, please take a look at:
- API Tutorial for R
- API Tutorial for Python
Before we get going, let’s first introduce the basic characteristics of the API. The base URL (i.e. hostname) of the Mapineq API is:
api.mapineq.org
The API is a collection “endpoints” that each provide a specific function. The following functions are available:
- get_levels
- get_source_by_nuts_level
- get_source_by_year_nuts_level
- get_year_nuts_level_from_source
- get_column_values_source_json
- get_x_data
- get_xy_data
Each function requires one or more parameters that you must specify. You can build an HTTP GET request by adapting the following URL to identify the function_name and parameter:value pairs:
https://api.mapineq.org/functions/postgisftw.function_name/item.json?parameter1=value¶meter2=value&limit=1000
You will replace “function_name” with your chosen function from the list above, and you will replace “parameter=value” with one or more parameters and their values. See the function documentation below for a complete list of parameters required for each function.
Note: Always use the parameter limit, otherwise you only get 10 values. Choose a value higher than the number of expected values.
Note: The API has a maximum of 10k items to return
Functions
get_levels
This endpoint returns of list of geographic levels (i.e. NUTS adminstrative units in Europe) that are available to query.
Parameters:
- None
Example Call:
Returns:
A list of geographic levels in JSON format:
[
{
"f_level": "3"
},
{
"f_level": "2"
},
{
"f_level": "1"
},
{
"f_level": "0"
}
]get_source_by_nuts_level
This endpoint returns a complete list of available data sources that are available for a specified geographic level.
Parameters:
- _level: (number; 0, 1, 2, 3)
Example Call:
Returns:
A list of data sources in JSON format:
[
{
"f_description": "All causes of death by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00057",
"f_short_description": "All causes of death "
},
{
"f_description": "Area by NUTS 3 region (ESTAT)",
"f_resource": "DEMO_R_D3AREA",
"f_short_description": "Area of regions"
},
{
"f_description": "At-risk-of-poverty rate by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00103",
"f_short_description": "At-risk-of-poverty"
},
{
"f_description": "Available beds in hospitals by NUTS 2 region (ESTAT)",
"f_resource": "HLTH_RS_BDSRG2",
"f_short_description": "Hospital beds"
},
{
"f_description": "Available beds in hospitals by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00064",
"f_short_description": "Hospital beds"
}
]Note: Only the first 5 json elements are shown
Notice that a value for f_resource is provided for each data set. This resource identifier will be used to query data from a specific data source from API endpoints described below.
get_source_by_year_nuts_level
This endpoint provides a list of available data sources for a specified year and geographic level.
Parameters:
- _year
- _level
Example Call:
Returns:
[
{
"f_description": "All causes of death by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00057",
"f_short_description": "All causes of death "
},
{
"f_description": "At-risk-of-poverty rate by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00103",
"f_short_description": "At-risk-of-poverty"
},
{
"f_description": "Available beds in hospitals by NUTS 2 region (ESTAT)",
"f_resource": "HLTH_RS_BDSRG2",
"f_short_description": "Hospital beds"
},
{
"f_description": "Available beds in hospitals by NUTS 2 regions (ESTAT)",
"f_resource": "TGS00064",
"f_short_description": "Hospital beds"
},
{
"f_description": "Business demography and high growth enterprise by NACE Rev. 2 and NUTS 3 regions (ESTAT)",
"f_resource": "BD_HGNACE2_R3",
"f_short_description": "Business demography "
}
]Note: Only the first 5 json elements are shown
get_year_nuts_level_from_source
This endpoint returns a list of all geographic levels and years that contain data for the specified data source.
Parameters:
- _resource: Resource identifier (i.e. f_resource returned by one of the “get_source” endpoints above)
Example Call:
Returns:
All combinations of geographic levels and years with data in JSON format:
[
{
"f_level": "0",
"f_year": "2008"
},
{
"f_level": "0",
"f_year": "2009"
},
{
"f_level": "0",
"f_year": "2010"
},
{
"f_level": "0",
"f_year": "2011"
},
{
"f_level": "0",
"f_year": "2012"
}
]Note: Only the first 5 json elements are shown
get_column_values_source_json
This endpoint provides a list of all filters that can be applied to a data source along with all possible values for each filter.
Parameters:
- _resource: (i.e. f_resource returned by one of the “get_source” endpoints above)
- source_selections: JSON containing year, level, and an empty selected array.
source_selections is a json formatted piece which contains always “year” ans “level” and a field “selected” which is an array, initially empty:
{
"year":"2020",
"level":"2",
"selected":[]
}Example Call:
Returns:
A list of filterable fields in JSON format:
[
{
"field": "unit",
"field_label": "Unit of measure",
"field_values": [
{
"label": "Percentage",
"value": "PC"
}
]
},
{
"field": "isced11",
"field_label": "International Standard Classification of Education (ISCED 2011)",
"field_values": [
{
"label": "All ISCED 2011 levels",
"value": "TOTAL"
},
{
"label": "Less than primary, primary and lower secondary education (levels 0-2)",
"value": "ED0-2"
},
{
"label": "Upper secondary and post-secondary non-tertiary education (levels 3 and 4)",
"value": "ED3_4"
},
{
"label": "Tertiary education (levels 5-8)",
"value": "ED5-8"
},
{
"label": "Unknown",
"value": "UNK"
},
{
"label": "No response",
"value": "NRP"
}
]
},
{
"field": "sex",
"field_label": "Sex",
"field_values": [
{
"label": "Total",
"value": "T"
},
{
"label": "Females",
"value": "F"
},
{
"label": "Males",
"value": "M"
}
]
},
{
"field": "freq",
"field_label": "Time frequency",
"field_values": [
{
"label": "Annual",
"value": "A"
}
]
},
{
"field": "age",
"field_label": "Age class",
"field_values": [
{
"label": "15 years or over",
"value": "Y_GE15"
}
]
}
]Advanced
Sometimes the filter values you can choose are dependent on the previously chosen values. For example, let’s take a look at the source Fertility Indicators (DEMO_R_FIND2).
The initial value for sources_selections would not include any “selected” values:
{
"year":"2019",
"level":"2",
"selected":[]
}Example call:
Result:
[
{
"field": "unit",
"field_label": "Unit of measure",
"field_values": [
{
"label": "Number",
"value": "NR"
},
{
"label": "Year",
"value": "YR"
}
]
},
{
"field": "indic_de",
"field_label": "Demographic indicator",
"field_values": [
{
"label": "Total fertility rate",
"value": "TOTFERRT"
},
{
"label": "Mean age of women at childbirth",
"value": "AGEMOTH"
},
{
"label": "Median age of women at childbirth",
"value": "MEDAGEMOTH"
}
]
},
{
"field": "freq",
"field_label": "Time frequency",
"field_values": [
{
"label": "Annual",
"value": "A"
}
]
}
]Notice that there are three options for Demographic Indicator (Mean age of women at childbirth, Median age of women at childbirth, and Total fertility rate).
Now, let’s choose “annual” for the unit of measure (i.e. unit=YR). To do tihs, we will revise the parameter source_selections:
{
"year":"2019",
"level":"2",
"selected":[{"field":"unit","value":"YR"}]
}This source selection will reduce the values available for the Demographic Indicator filter:
Example call:
Result:
[
{
"field": "unit",
"field_label": "Unit of measure",
"field_values": [
{
"label": "Year",
"value": "YR"
}
]
},
{
"field": "indic_de",
"field_label": "Demographic indicator",
"field_values": [
{
"label": "Mean age of women at childbirth",
"value": "AGEMOTH"
},
{
"label": "Median age of women at childbirth",
"value": "MEDAGEMOTH"
}
]
},
{
"field": "freq",
"field_label": "Time frequency",
"field_values": [
{
"label": "Annual",
"value": "A"
}
]
}
]Notice that there are now only two options for Demographic Indicator (Mean age of women at childbirth and Median age of women at childbirth).
get_x_data
With this endpoint, you can retrieve data for a specific source.
Parameters:
- _level: Geographic level
- _year: Year of data
- X_JSON: JSON specifying the source and filters
Example Call:
Returns:
[
{
"data_year": "2018",
"geo": "AL01",
"geo_name": "Veri",
"geo_source": "NUTS",
"geo_year": "2021",
"x": null
},
{
"data_year": "2018",
"geo": "AL02",
"geo_name": "Qender",
"geo_source": "NUTS",
"geo_year": "2021",
"x": null
},
{
"data_year": "2018",
"geo": "AL03",
"geo_name": "Jug",
"geo_source": "NUTS",
"geo_year": "2021",
"x": null
},
{
"data_year": "2018",
"geo": "AT11",
"geo_name": "Burgenland",
"geo_source": "NUTS",
"geo_year": "2021",
"x": 4.2
},
{
"data_year": "2018",
"geo": "AT12",
"geo_name": "Nieder\u00f6sterreich",
"geo_source": "NUTS",
"geo_year": "2021",
"x": 3.8
}
]Note: Only the first 5 json elements are shown
get_xy_data
This endpoint allows you to retrieve data for two sources joined by location.
Parameters:
- _level: Geographic level
- _predictor_year: Year of predictor (X) data
- _outcome_year: Year of outcome (Y) data
- X_JSON: JSON specifying the first source and filters.
- Y_JSON: JSON specifying the second source and filters.
Example Call:
Returns:
A list of geographic units with x and y values:
[
{
"geo": "AL01",
"geo_name": "Veri",
"geo_source": "NUTS",
"geo_year": "2018",
"outcome_year": "2018",
"predictor_year": "2018",
"x": null,
"y": null
},
{
"geo": "AL02",
"geo_name": "Qender",
"geo_source": "NUTS",
"geo_year": "2018",
"outcome_year": "2018",
"predictor_year": "2018",
"x": null,
"y": null
},
{
"geo": "AL03",
"geo_name": "Jug",
"geo_source": "NUTS",
"geo_year": "2018",
"outcome_year": "2018",
"predictor_year": "2018",
"x": null,
"y": null
},
{
"geo": "AT11",
"geo_name": "Burgenland",
"geo_source": "NUTS",
"geo_year": "2018",
"outcome_year": "2018",
"predictor_year": "2018",
"x": 4.2,
"y": 81.5
},
{
"geo": "AT12",
"geo_name": "Nieder\u00f6sterreich",
"geo_source": "NUTS",
"geo_year": "2018",
"outcome_year": "2018",
"predictor_year": "2018",
"x": 3.8,
"y": 81.5
}
]Note: Only the first 5 json elements are shown