Application Programming Interface (API)

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]

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 service identifier determines the root element of the returned document.

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:

• xml: returns the result in eXtensible Markup Language format.
• json: returns the result in JavaScript Object Notation format. This output faithfully reproduces all the information returned for the request in XML 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

2.1 Response codes

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 three types of request that return different HTTP response codes:

• Correct: returns response code 200 (OK).
• Unspecified, or incorrectly specified service, version, operation or format: returns response code 404 (Not Found), unless all these specifications are missing. In the latter case, it redirects (301) to this documentation.
• No specification of a required parameter of the specified service/operation: returns response code 400 (Bad Request).

In the latter case, the document returned will contain information from the service that has generated it, the error code (within the error element) and the compulsory parameter or parameters for which the value has not been specified (within a missing element for each missing parameter).

Ex. 8: Wrong request

http://api.idescat.cat/indicadors/v1/dades.xml?i=

Ex. 9: Content of the response to the wrong request

<?xml version="1.0" encoding="utf-8" ?>
<indicadors version="1.00" o="dades">
   <error>400</error>
   <missing>i</missing>
</indicadors>

2.2 Supported formats

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