Idescat > Developers Area > API

Application Programming Interface (API) RSS

01.14.2014

Idescat exposes some of its data via a collection of REST APIs (RESTful Web Services). Idescat's APIs offer methods for third-party programs to be able to obtain information from the Statistical Institute of Catalonia and integrate it in other services. The use of any of Idescat's APIs requires acceptance of the service terms of use.

Summary
Base URI http://api.idescat.cat/{service}/v{main version}/{operation}.{format}[?parameters]
HTTP Method GET
Response Formats xml, json, php
Version 1.00 (12.14.2009)
Shortcuts Request, Response

Terms of use

  1. You must recognise the origin of the data, either using the links provided by the APIs, or linking to Idescat.cat.
  2. You are not authorised to show the content provided by the APIs in any way that does not permit access to links to Idescat's pages. Neither are you authorised to include an Idescat web page in any frame (<frame>, <iframe>).
  3. In presenting them, you are not authorised to modify or edit the data, metadata or links provided by the APIs.
  4. You must ensure that the meaning of the content provided by the APIs is not changed or distorted.
  5. The use of Idescat's APIs does not assume any kind of support, relation or affiliation between the service using them and the Statistical Institute of Catalonia. You are not authorised to show the information provided by Idescat's APIs in any way that suggests any such support, relation or affiliation.
  6. Idescat reserves the right to limit repeated requests from the same origin in order to guarantee everybody can access the service. It is your own responsibility to employ the necessary mechanisms to avoid requests for the same information within short periods of time. Excessive use can lead to finalisation of the service. If you intend to make intensive use of Idescat's APIs please contact Idescat in order to guarantee that this use does not damage the availability of the data in general.
  7. Any transfer, use or exploitation of the APIs must comply with the stipulations contained in current legislation and must always be associated to legitimate uses.
  8. In the case of any violation of these conditions, Idescat reserves the right to deactivate your access to the APIs. You will also be responsible for any damages caused by improper exploitation of this information.
  9. Idescat reserves the right to modify at its discretion these conditions at any time, and also to terminate this relationship or cancel your use, and declines any express or implicit guarantee in relation to this service.

1. Request

1.1. Anatomy of requests

All requests must specify a service, the main version of the service, a valid operation for the service and a response format. Optionally, a series of general and specific parameters for the service can be specified.

http://api.idescat.cat/{service}/v{main version}/{operation}.{format}[?parameters]

Some services can share the syntax of requests and the structure of responses. These are treated as a single service that offers subservices. In this case, the form of the request is:

http://api.idescat.cat/{service}/v{main version}/{subservice}/{operation}.{format}[?parameters]

Although this is the form by which all requests are treated internally, the APIs also usually admit a more user-friendly external syntax that does not require an operation to be specified (see Invocation without operation).

1.1.1. Service and version

Each service has an identifier, a version and some specific parameters. For example, the Indicators of the day service is identified using the value indicators and has only one version (1).

Ex. 1: Request in version 1 of the Indicators of the day service
http://api.idescat.cat/indicadors/v1/{…}

The services may have different main versions that are incompatible with each other. Incremental improvements do not affect the main version (for example, 1.01 with respect to 1.00) and therefore do no affect the request either.

1.1.2. Operation

The services tend to support a diversity of operations. For example, the service indicators admits the operation data, which returns statistical results, but also the operation nodes.

Ex. 2: Two requests for the same service but different operations
http://api.idescat.cat/indicadors/v1/dades.{…}
http://api.idescat.cat/indicadors/v1/nodes.{…}

The identifier and the operation determine the structure of the returned document.

1.1.3. Format

It determines the response format. It admits three values in general:

  • xml: returns the result in eXtensible Markup Language format.
  • json: returns the result in JavaScript Object Notation format. It enables specification of a callback function using the parameter callback with the name of the function. Although JSON is a UTF-8 encoded string, for reasons of convenience, the output in this format takes into account the specified value for enc.
  • php: returns the result in serialised PHP format. This output has the same structure as that of output in JSON format: it is a string that can be deserialised to create a PHP object (not an array). In this case, the result is always returned UTF-8 encoded regardless of the value for enc.
Ex. 3: Different requests with different response formats
http://api.idescat.cat/indicadors/v1/dades.xml
http://api.idescat.cat/indicadors/v1/dades.php
http://api.idescat.cat/indicadors/v1/dades.json
http://api.idescat.cat/indicadors/v1/dades.json?callback=f

1.2. General parameters

Every request has some general parameters (common to all services) and some specific parameters of the service, documented in the API of the service.

1.2.1. Response language (lang)

It admits three values:

  • ca: Catalan (default value)
  • es: Spanish
  • en: English
Ex. 4: Result in Spanish
http://api.idescat.cat/indicadors/v1/dades.xml?lang=es

1.2.2. Response encoding (enc)

This parameter admits two values: utf-8 (default value) and iso-8859-1.

Ex. 5: ISO-8859-1 encoded result
http://api.idescat.cat/indicadors/v1/dades.xml?enc=iso-8859-1

If the response output is php the encoding is UTF-8, whatever the value for enc.

1.3. Specific parameters

As well as the general parameters described in the previous section, each service admits certain specific parameters ("variables") that can configure the information obtained. These parameters are documented in the service's API.

For example, the operation data of the service indicators can be used to select the number of indicators obtained thanks to the parameters tt, max and min.

Ex. 6: Specific parameters
http://api.idescat.cat/indicadors/v1/dades.xml?tt=10&max=10&min=3

1.3.1. General parameter p

The service variables (or "specific parameters") can be encapsulated in a general parameter to make a more compact call. To do so, a series of variable/value pairs must be included separated by semicolons.

Ex. 7: Synonymous requests
http://api.idescat.cat/indicadors/v1/dades.json?tt=10&max=10&min=3
http://api.idescat.cat/indicadors/v1/dades.json?p=tt/10;max/10;min/3

1.4. Invocation without operation

For reasons of user-friendliness, some APIs can admit requests with a syntax that does not require one of the generally provided operations to be specified. Instead, they use references to resources that tend to be specific to each API. See the documentation on each API to find out whether the invocation without operation is available and its specific syntax.

As APIs always use the invocation with operation internally, the error messages include the requests in this form, regardless of how they were specified by the user.

2. Response

2.1. Response codes and errors

Should the server not be able to attend to the request, the code returned will be 500 (Server Error) or 503 (Service Unavailable). In other cases, we can distinguish two types of request that return different HTTP response codes:

  • Correct: returns response code 200 (OK).
  • Incorrect: returns response code 400 (Bad Request). As some clients intercept the content of the response when the code is an error, for convenience code 200 (OK) can be forced, adding to the request the rc parameter with value 200 (this parameter will be ignored if another value is specified).

In the case of incorrect request, the returned document will contain the error code (id), an explanatory text in the language required by the request (text) and the request (query) as interpreted by the APIs server. If the request did not specify one of the formats provided for an API, it will use XML in the response.

Ex. 8: Content of an XML response to a request in an erroneous format
<?xml version="1.0" encoding="utf-8" ?>
<errors>
   <error>
      <id>105</id>
      <text xml:lang="en">
          "sas" is not a valid format (xml, json, php) for the cerca operation in version v1 of the service pob.
      </text>
   </error>
   <query>http://api.idescat.cat/pob/v1/cerca.sas?q=abrera&amp;lang=en</query>
</errors>
Ex. 9: Content of a JSON response to a request in an inexistent format
{
   "error":[
      {
         "id":"104",
         "text":"\"search\" is not a valid operation (cerca, sug) for version v1 of the service pob."
      }
   ],
   "query":"http:\/\/api.idescat.cat\/pob\/v1\/search.json?q=abrera&lang=en"
}
Ex. 10: Content of a response in serialised PHP format to a request without version
a:2:{
   s:5:"error";
   a:1:{
      i:0;
      a:2:{
         s:2:"id";
         s:3:"002";
         s:4:"text";
         s:79:"For the indicadors service, you must specify a version (v1).";
      }
   }
   s:5:"query";
   s:55:"http:\/\/api.idescat.cat\/indicadors\/dades.php?lang=es";
}
Ex. 11: Content of a response in text format to a request that does not support this format for the specified service/version/operation
***ERROR***
105
"txt" is not a valid format (xml, json, php) for the cerca operation in version v1 of the service pob.
http://api.idescat.cat/pob/v1/cerca.txt?q=abrera&lang=en

The error codes indicate that a required information has not been specified or that this has been done using an incorrect value (and the information does has a default value):

Error codes
Missing Incorrect value
Service 001 101
Version 002 102
Subservice 003 103
Operation 004 104
Format 005 105
Parameter 006 106

2.2. Supported formats

At present, the response formats supported in general are XML, JSON and serialised PHP. For further information, see section 1.1.3. Format.

01.14.2014