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.

https://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:

https://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

https://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

https://api.idescat.cat/ indicadors /v1 / dades .{…}

https://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.

: 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 .

: returns the result in JavaScript Object Notation format. It enables specification of a callback function using the parameter 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 . 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

https://api.idescat.cat/ indicadors /v1 / dades . xml

https://api.idescat.cat/ indicadors /v1 / dades . php

https://api.idescat.cat/ indicadors /v1 / dades . json

https://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)

: Catalan (default value) es : Spanish

: Spanish en : English

Ex. 4: Result in Spanish

https://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

https://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

https://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

https://api.idescat.cat/indicadors /v1 /dades.json ? tt = 10 & max = 10 & min = 3

https://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.