Tables. API 
The Tables service returns data and metadata from a growing set of Idescat statistics.
The use of this service requires acceptance of the Terms of use of Idescat's APIs.
| Base URI | https://api.idescat.cat/taules/v2/{statistics}/{node}/{table}/{geo}[/data][?{filters}] |
|---|---|
| HTTP Methods | GET, POST |
| Response Formats | json (JSON-stat) |
| Version | 2.00 (18/9/2023) |
1. Request
1.1 Statistics available
https://api.idescat.cat/taules/v2
Returns a list of the statistics available through the API as a JSON-stat collection.
1.2 Nodes available
https://api.idescat.cat/taules/v2 /{statistics}
Returns a list of the nodes available for a statistic as a JSON-stat collection.
Ex. 1: Nodes for the PMH statistics (Municipal Population Register)
https://api.idescat.cat/taules/v2 /pmh
1.3 Tables available
https://api.idescat.cat/taules
Returns a list of the tables available for a statistic in a specific node as a JSON-stat collection.
Ex. 2: Tables from node 1180 ("Population as of 1 January. By sex and age year by year") for the PMH statistics (Municipal Population Register)
https://api.idescat.cat/taules/v2 /pmh /1180
1.4 Territorial divisions available
https://api.idescat.cat/taules/v2 /{statistics} /{node} /{table}
Returns a list of the territorial divisions available for a specific table as a JSON-stat collection.
Ex. 3: Territorial divisions of table 8078 ("Population as of 1 January. By sex and age year by year (2014–)") from node 1180 for the PMH statistics (Municipal Population Register)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078
1.5 Metadata from a table
https://api.idescat.cat/taules/v2 /{statistics} /{node} /{table} /{geo}
Returns the metadata from a table for a specific territorial division as a JSON-stat dataset.
Ex. 4: Metadata from table 8078 ("Population as of 1 January. By sex and age year by year (2014–)") by counties and Aran from node 1180 for the PMH statistics (Municipal Population Register)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com
The response to this request is identical to the data request, except it contains no data.
The request for the table data is exposed in the describes property.
1.6 Data from a table
https://api.idescat.cat/taules/v2 /{statistics} /{node} /{table} /{geo} /data
Returns the data from a table for a specific territorial division as a JSON-stat dataset.
The API does not permit the retrieval of more than 10,000 20,000 data in a single call. See section 1.7 on how to filter the number of cells returned.
Ex. 5: Metadata from table 8078 ("Population as of 1 January. By sex and age year by year (2014–)") by counties and Aran from node 1180 for the PMH statistics (Municipal Population Register)
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data
The request for only the metadata of the table is exposed in the describedby property.
1.7 Parameters
1.7.1 The general parameter lang
All calls support the lang parameter to determine the language of the response. This parameter supports three values: ca (default value), es and en.
Ex. 6: Nodes for the PMH statistics (Municipal Population Register) in English
https://api.idescat.cat/taules/v2 /pmh ?lang=en
1.7.2 Filters
When retrieving data or metadata, categories can be filtered from the dimensions of the table. To do this, you must know the names of the categories and dimensions, as they appear in the metadata request described in section 1.5. Only the categories with comma-separated values will be retrieved for the dimensions that appear as parameters in the call.
Ex. 7: Female population by age year by year in L’Alt Camp and Catalonia as a whole
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01,TOTAL
Ex. 8: Female population by age year by year in L’Alt Camp for 2020 and 2021
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&YEAR=2020,2021
To avoid the limitation imposed by the HTTP/1.1 protocol on the addresses, this API exceptionally supports the POST method: this method must only be used when the complexity of the filters would result in an address of a GET request longer than 2,000 characters. Example:
Address: https://api.idescat.cat/taules
Message body: SEX=F&COM=01,
1.7.3 The time parameter _LAST_
In addition to filtering the data by specifying the desired values for the time dimension, they can also be filtered by the number of last periods required.
Ex. 9: Female population by age year by year in L’Alt Camp for the last two available years
https://api.idescat.cat/taules/v2 /pmh /1180 /8078 /com /data ?SEX=F&COM=01&_LAST_=2
2. Response
2.1 Classes
The API returns three classes of response: collection (JSON-stat collection), dataset (JSON-stat dataset) and error. For the first two, see the JSON-stat documentation JSON-stat.
When an error occurs, the response takes the following form:
{
version: "2.0",
class: "error",
status: "{Status code HTTP}",
id: "{Internal error code}",
label: "{Explanatory text}"
}
For example, when the data limit is exceeded, the API returns:
{
version: "2.0",
class: "error",
status: "416",
id: "05",
label: "Data limit exceeded."
}
| Internal code | Description | HTTP status code |
|---|---|---|
| 01 | Incorrect statistic identifier. | 400 |
| 02 | Incorrect node identifier. | 400 |
| 03 | Incorrect table identifier. | 400 |
| 04 | Incorrect territorial division identifier. | 400 |
| 05 | Data limit exceeded. | 416 |
| 06 | Incorrect _LAST_ parameter value. | 400 |
| 00 | Serious API error. | 500 |
2.2 Extensions
JSON-stat supports response customisation using the extension property, associating it to the dataset or a specific dimension. The API uses this property in a number of different situations.
2.2.1 Status
The status property associates a symbol (e.g. "p") to values with any special status. The API uses a dataset level extension to associate a text (e.g. "Provisional data") to the symbols used.
"extension": {
"status": {
"label": {
"p": "Provisional data"
}
}
}
Sometimes the status attributed to a value is derived from the status associated with a dimension category. For example, the provisional nature of data is often associated with a specific time period. The API uses a dimension-level extension to attach a status to some of its categories.
"extension": {
"status": {
"2022": "p"
}
}
2.2.2 Source
In addition to using the JSON-stat (text) source property, the API returns a vector with the different sources associated with the table as an extension of the dataset.
"extension": {
"source": [
"Idescat, from the INE's Continuous Population Register."
]
}
2.2.3 Changes to the geographical dimension
Dimensions with a geographical role identify the granularity of the territorial division used, e.g., "by county" (COM), "by municipality" (MUN), etc. The version of the territorial division and any changes that may have been introduced are displayed in an extension associated with that geographical dimension in question.
"COM" :
"label" : "county or Aran",
"extension" : {
"break" : [ {
"time" : "2010",
"id" : "COM41",
"label" : "Counties valid on 17/01/1990"
}, {
"time" : "2015",
"id" : "COM42",
"label" : "Counties valid on 01/05/2015"
} ]
}
}
For the identifier of the initial period of application of a new version of the territorial division, the internal identifier of the geographical classification and a descriptive text are indicated. The time property indicates the category of the first dimension with a time role.
2.2.4 Other extensions
Other extensions may be added to the response in the future and will be included in this documentation as appropriate. See also 2.3.3 Related requests.
2.3 Links
JSON-stat uses the link property to provide links related to the API call, grouped by relationships. When links return responses in JSON-stat format, three JSON-stat properties are exposed: class, href and label. When they do not, the API exposes two properties: type (content type) and href.
2.3.1 Data and metadata
The binding between metadata and its data is exposed in the describes property.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com?lang=en",
"link" : {
"describes" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data?lang=en",
"label" : "Population at 1 January. By sex. Counties and Aran"
} ],
…
},
…
}
The binding between data and its metadata is exposed in the describedby property.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com/data?lang=en",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com?lang=en",
"label" : "Population at 1 January. By sex. Counties and Aran"
} ],
…
},
…
}
2.3.2 Corrections
Information about any recent corrections that may have been introduced to the data is exposed with the monitor property.
"link" : {
"monitor" : [ {
"type" : "application/json",
"href" : "https://api.idescat.cat/rectificacions/v1/rectificacions/cerca.json?id=485&lang=en"
} ],
…
}
This link with the Corrections API may include one or more corrections.
2.3.3 Related requests
Other related requests are exposed with related type properties. In this section you can find the calls to the metadata of the same table for different territorial divisions (same node identifier, same table identifier, different geographical identifier):
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/prov?lang=en",
"label" : "Population at 1 January. By sex. Provinces"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/at?lang=en",
"label" : "Population at 1 January. By sex. Areas of the Territorial Plan"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/com?lang=en",
"label" : "Population at 1 January. By sex. Counties and Aran"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/mun?lang=en",
"label" : "Population at 1 January. By sex. Municipalities"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/ac?lang=en",
"label" : "Population at 1 January. By sex. By census tract group"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/dis?lang=en",
"label" : "Population at 1 January. By sex. Census districts"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pmh/446/477/sec?lang=en",
"label" : "Population at 1 January. By sex. Census sections"
} ]
You can also find the calls to the metadata of the different tables that the same node has had over time (same node identifier, different table identifier, same geographical identifier):
{
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/1/cat?lang=en",
"label" : "Population. By sex and age year by year. Catalonia (1981–2001)"
}, {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/censph/10/5464/cat?lang=en",
"label" : "Population. By sex and age year by year. Catalonia (1975)"
}
Exceptionally, tables of different nature that tend to be presented together can share a node identifier. This case can be distinguished from the previous one thanks to the group extension with the value true.
{
"version" : "2.0",
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat/data?lang=en",
"link" : {
"describedby" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15840/cat?lang=en",
"label" : "Gross Domestic Product at current prices. Supply. Seasonally adjusted data. Catalonia"
} ],
"related" : [ {
"class" : "dataset",
"href" : "https://api.idescat.cat/taules/v2/pibt/13077/15841/cat?lang=en",
"label" : "Gross Domestic Product at current prices. Demand. Seasonally adjusted data. Catalonia",
"extension" : {
"group" : true
}
} ]
},
…
}
2.3.4 Other links
Other links may be added to the response in the future and will be included in this documentation as appropriate.