Rectifications. 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 rectifications 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.

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

1.1.2. Operations

This service admits two types of operation:

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

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

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

  http://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 rectifications.

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

http://api.idescat.cat/rectificacions/v1/cerca.json?enc=iso-8859-1&lang=en

To access the most recent rectifications 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 rectification 21

http://api.idescat.cat/rectificacions/v1/cerca.xml?posicio=20&lang=en

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

Ex. 3: Information on the rectification with identifier 27

http://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 rectifications. 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 rectifications of the category "treball" in the classification by "tema"

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

To include more than one category, use a comma.

Ex. 5: List of rectifications of the category "treball" or of the category "turisme" in the classification by "tema"

http://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema&id=treball,turisme&lang=en

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

Ex. 6: List of rectifications with "servei" equal to "aec" and with "tema" equal to "treball" or to "turisme"

http://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema+servei&id=treball,turisme+aec&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 rectification was made (updated). One must specify at least one day, month and year in the format YYYYMMDD.

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

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

To define an interval, use a hyphen.

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

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

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

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

http://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.
• 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 rectifications in serialised PHP format

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

http://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 rectifications in XML format

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

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

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

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

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

• List of rectifications of the category "treball" in the criterion "tema" in XML format

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

• Information on the rectification with identifier 27 in XML format

  http://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 Rectifications API uses the standard Atom, as it treats lists of rectifications (cerca operation) as categorisation criteria or categories (categories operation).

2.1. Operation cerca

To describe rectifications, 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 rectification.

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 rectified and the updated element for the date when the rectification 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 rectification 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 rectification 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="http://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="http://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="http://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
   term="treball"
   label="Labour"
   xml:lang="en"
/>
<category
   scheme="http://api.idescat.cat/rectificacions/v1/categories.xml?id=servei&amp;lang=en"
   term="aec"
   label="Statistical Yearbook of Catalonia "
   xml:lang="en"
/>
<category 
   scheme="http://api.idescat.cat/rectificacions/v1/categories.xml?id=servei&amp;lang=en"
   term="epa"
   label="Active Population Survey"
   xml:lang="en"
/>

2.2. Operation categories

The categories operation exposes the categorisation of the rectifications 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="http://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>macromagnituds</title>
  <content xml:lang="en">Macro magnitudes</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="http://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 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="http://api.idescat.cat/rectificacions/v1/categories.xml?id=tema&amp;lang=en"
    type="application/atom+xml"
  />
  <updated>2010-10-15</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/macromagnituds</id>
  <title>macromagnituds</title>
  <content xml:lang="en">Macro magnitudes</content>
  <updated>2010-10-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 rectification ("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="http://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 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.