Corrections. API

1.1. Basic characteristics

Every request must by obligation specify the service, version, operation and format. Version and operation are specific characteristics of each service. The corrections service supports the formats for general responses of Idescat APIs. For more information, see the Anatomy of requests sections of the general documentation on Idescat APIs.

1.1.1. Identifier of service and version

The identifier of this service is rectificacions.

https://api.idescat.cat/rectificacions/v1/{…}

1.1.2. Operations

This service admits two types of operation:

• cerca: Returns the corrections that comply with the selection criterion.

  https://api.idescat.cat/rectificacions/v1/cerca.{…}

• categories: Provides information on the categories used in the categorisation of corrections.

  https://api.idescat.cat/rectificacions/v1/categories.{…}

1.2. Specific parameters

The specific parameters make it possible to choose the information that will be returned by a certain operation of the service. These can be specified as individual parameters or as a unique parameter p (compact form).

To find out about the general parameters available for any service, please see the documentation on Idescat APIs.

1.2.1. Operation cerca

The operation cerca can be invoked without using any specific parameters (unfiltered results). In this case, it will return the older corrections.

Ex. 1: List of older corrections in JSON format and ISO-8859-1 enconding

https://api.idescat.cat/rectificacions/v1/cerca.json?enc=iso-8859-1

To access the most recent corrections you must use the parameter desc (or the parameter posicio).

1.2.1.1. posicio

As some searches can return a very high number of results, the response will not always include all of them. The parameter posicio makes it possible to specify which should be the first result to be included in the response. By default, posicio equals zero.

Ex. 2: List starting from correction 21

https://api.idescat.cat/rectificacions/v1/cerca.xml?posicio=20

The elements of the responses opensearch:totalResults and opensearch:itemsPerPage make it possible to determine whether all of the results are shown or not.

1.2.1.2. id

When not accompanied by the scheme parameter (see following section), the id parameter enables selection of the information on an individual correction.

Ex. 3: Information on the correction with identifier 27

https://api.idescat.cat/rectificacions/v1/cerca.xml?id=27&lang=en

1.2.1.3. scheme

This parameter, accompanied by the id parameter, makes it possible to filter the results for some of the categories used in the categorisation of the corrections. To find out the categorisation criteria, use the operation categories.

The scheme parameter is used to select the criterion and the id parameter is used to select the category.

Ex. 4: List of corrections of the category labour ("treba") in the classification by "tema"

https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema&id=treba&lang=en

To include more than one category, use a comma.

Ex. 5: List of corrections of the category labour ("treba") or of the category tourism ("turis") in the classification by "tema"

https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema&id=treba,turis&lang=en

To simultaneously filter according to two criteria use "+" in the parameter scheme and id:

Ex. 6: List of corrections with statistic ("estad") equal to "afi" and with "tema" equal to labour ("treba") or to tourism ("turis")

https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema+servei&id=treba,turis+afi&lang=en

1.2.1.4. published and updated

These parameters filter the results according to a period of time: according to the date on which the information was published (published) and according to the date when the correction was made (updated). One must specify at least one day, month and year in the format YYYYMMDD.

Ex. 7: List of corrections from January 1, 2010 to the present

https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20100101&lang=en

To define an interval, use a hyphen.

Ex. 8: List of corrections from January 1 to 31, 2010 (both inclusive)

https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20100101-20100131&lang=en

The hyphen can be used to select the corrections on a certain day.

Ex. 9: List of corrections on October 8, 2010

https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20101008-20101008&lang=en

1.2.1.5. orderby and desc

By default, the results are shown in ascending order of the date of update (updated). The parameters orderby and desc will modify this criterion.

• orderby
  • updated: Ordered by date of update. This is the default value.
  • published: Ordered by date that the information was published before it was updated.
  • title: Ordered by the name of the information affected by the update. This order is language dependent.
  • tema: Ordered by the text describing the updated issue. This order is language dependent.
  • estad: Ordered by the statistics identifier.
• desc
  • 0: Ascending order. This is the default value.
  • 1: Descending order.

1.2.2. Operation categories

The categories operation can be invoked without using any specific parameter in order to obtain the identifiers of the criteria for the categorisation of the information.

Ex. 10: List of categorisation criteria of the corrections in serialised PHP format

https://api.idescat.cat/rectificacions/v1/categories.php?lang=en

The identifiers returned can be used as an id parameter (see following section) in order to obtain their categories.

1.2.2.1. id

To obtain the categories used in a certain criterion, use the id parameter.

Ex. 11: List of categories of the criterion "tema" in XML format

https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&lang=en

1.3. Invocation without operation

As in the case of other APIs, this one also accepts requests with a syntax that does not require the specification of operations (categories and cerca, in this case; see the general documentation on Idescat APIs, section 1.4. Invocation without operation). However, the advantages of this type of invocation are less clear than for other APIs because it does not imply any significant simplification of the requests, as they still require the use of two types of resource (categories and rectificacions).

• List of the categorisation criteria of the corrections in XML format

  https://api.idescat.cat/rectificacions/v1/categories.xml?lang=en

• List of categories of the criterion "tema" in JSON format

  https://api.idescat.cat/rectificacions/v1/categories/tema.json?lang=en

• List of corrections on October 8, 2010 in serialised PHP format

  https://api.idescat.cat/rectificacions/v1/rectificacions.php?updated=20101008-20101008&lang=en

• List of corrections of the category labour ("treba") in the criterion "tema" in XML format

  https://api.idescat.cat/rectificacions/v1/rectificacions.xml?scheme=tema&id=treba&lang=en

• Information on the corrections with identifier 27 in XML format

  https://api.idescat.cat/rectificacions/v1/rectificacions/27.xml?lang=en

In order to find out the HTTP response codes returned and the formats supported by any service, see section 2 of Idescat APIs.

To describe the information, the Corrections API uses the standard Atom, as it treats lists of corrections (cerca operation) as categorisation criteria or categories (categories operation).

2.1. Operation cerca

To describe corrections, the cerca operation uses the standard Atom enriched with elements of the standard OpenSearch. See the documentation on these standards to find out about the response structure of the cerca operation: only some elements of the entry element that have special uses are documented here.

2.1.1. title

The cerca operation uses the title element to specify the information affected by the corrections.

Ex. 12: Element title

<entry>
   <title xml:lang="en">Registered unemployment</title>
   ...
</entry>

2.1.2. published and updated

The cerca operation uses the published element to specify the date on which the information was published before being corrected and the updated element for the date when the correction was made.

Ex. 13: published and updated elements

<published>2009-01-10</published>
<updated>2010-02-15</updated>

2.1.3. content

The cerca operation includes the description of the corrections of the content element in XHTML format.

Ex. 14: content element

<content xml:lang="en" type="xhtml">
   <div xmlns="http://www.w3.org/1999/xhtml">
      ...
   </div>
</content>

2.1.4. link

The links to the pages affected by the correction are included in link elements with an attribute rel that is equal to via. The title attribute is used to offer a description of the page affected in the requested language.

Ex. 15: link elements with rel equal to via

<link
   rel="via"
   xml:lang="en"
   type="text/html"
   href="https://www.idescat.cat/pub/?id=lma&amp;n=8.3.1.1&amp;lang=en"
   title="People aged 16 or more that are in favour of taking measures for the protection of the environment.
            By territorial areas and type of measure"
/>
<link
   rel="via"
   xml:lang="en"
   type="text/html"
   href="https://www.idescat.cat/pub/?id=lma&amp;n=8.3.1.2&amp;lang=en"
   title="People aged 16 or more that are in favour of taking measures for the protection of the environment.
            By size of municipality and type of measure"
/>

2.1.5. category

The cerca operation classifies the different results using category elements. The scheme attribute indicates the categorisation criterion with the request to the API that returns its list of possible categories (see section 2.2.). The term attribute indicates the identifier of the category. The label attribute includes a descriptive literal of the category in the language of the request.

Ex. 16: category elements

<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
   term="xifpo"
   label="Population figures"
   xml:lang="en"
/>
<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=servei&amp;lang=en"
   term="ep"
   label="Population Estimates"
   xml:lang="en"
/>
<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=servei&amp;lang=en"
   term="annuals"
   label="Annual indicators"
   xml:lang="en"
/>

2.2. Operation categories

The categories operation exposes the categorisation of the corrections using the standard Atom. See the documentation on these standards to find out about the response structure of the categories operation: only some elements of the entry element that have special uses are documented here.

2.2.1. title

When the categories operation is invoked without a parameter id (list of categorisation criteria), the title element of each entry includes the identifier of the categorisation criterion.

Ex. 17: title element in an invocation without id

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="en">Topics</content>
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
    type="application/atom+xml"
  />
  <updated>2010-10-15</updated>
</entry>

When the categories operation is invoked with an id parameter (list of categories of the selected criterion), the title element of each entry includes the identifier of the category.

Ex. 18: title element in an invocation with id equal to "tema"

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema/macromagnituds</id>
  <title>macro</title>
  <content xml:lang="en">Main aggregates</content>
  <updated>2010-10-15</updated>
</entry>

2.2.2. link

When the categories operation is invoked without an id parameter (list of categorisation criteria), the link element of each entry includes in its href attribute the request to the API for the list of categories of the specified criterion in the title element of the entry.

Ex. 19: link element in an invocation without id

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="en">Topics</content>
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

When the categories operation is invoked with an id parameter (list of categories of the selected criterion), the link element does not appear.

2.2.3. content

When the categories operation is invoked without an id parameter (list of categorisation criteria), the content element includes the literal associated to the identifier of the categorisation criterion that appears in the title element.

Ex. 20: content element in an invocation without id

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="en">Topics</content >
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

This same literal appears within the title element of feed when the categories operation is invoked with id.

Ex. 21: title element of feed in an invocation with an id equal to "tema"

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title xml:lang="en">Topics</title>
  <category term="1" />
  ...
</feed>

When the categories operation is invoked with an id parameter (list of categories of the selected criteria), the content element includes the literal associated to the identifier of the category that appears in the title element.

Ex. 22: content element in an invocation with an id equal to "tema"

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema/macro</id>
  <title>macro</title>
  <content xml:lang="en">Main aggregates</content>
  <updated>2011-09-15</updated>
</entry>

2.2.4. category

The categories operation uses the term attribute of the category element to express whether one and only one category of the criterion in question should appear for each correction ("1"), whether at least one should appear but more can appear ("+"), whether more than one can appear but also none ("*") or whether the category has to be unique but there can be none ("?").

When the categories operation is invoked without an id parameter (list of categorisation criteria), the category element is associated to each entry element.

Ex. 23: category element in an invocation without id

<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="en">Topics</content >
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

When the categories operation is invoked with an id parameter (list of categories of the selected criterion), the category element is associated to the feed element.

Ex. 24: category element of feed in an invocation with an id equal to "tema"

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title xml:lang="en">Topics</title>
  <category term="1" />
  ...
</feed>

2.3. Errors

Idescat APIs use standardised response codes to show whether the request has been successful or has failed.