Saltar al contingut principal

Rectificacions. API RSS

L'API de Rectificacions dona accés a la informació del registre de rectificacions del lloc web de l'Idescat.

La utilització d'aquest servei comporta l'acceptació de les condicions d'ús de les APIs de l'Idescat.

Resum
URI base https://api.idescat.cat/rectificacions/v1/{operació}.{format}[?paràmetres]
Mètode HTTP GET
Formats de la resposta xml, json, php
Versió 1.00 (20/10/2010)
Dreceres Petició, Resposta
Operacions cerca, categories

1. Petició

1.1. Característiques bàsiques

Tota petició ha d'especificar obligatòriament el servei, la versió, l'operació i el format. Versió i operació són característiques específiques de cada servei. El servei de Rectificacions suporta els formats de resposta generals de les APIs de l'Idescat. Per a més informació, consulteu l'apartat Anatomia de les peticions a la documentació general de les APIs de l'Idescat.

1.1.1. Identificador del servei i versió

L'identificador d'aquest servei és rectificacions.

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

1.1.2. Operacions

Aquest servei admet dos tipus d'operacions:

  • cerca: Retorna les rectificacions que compleixen el criteri de selecció.
    https://api.idescat.cat/rectificacions/v1/cerca.{…}
  • categories: Permet obtenir informació sobre les categories emprades en la categorització de les rectificacions.
    https://api.idescat.cat/rectificacions/v1/categories.{…}

1.2. Paràmetres específics

Els paràmetres específics permeten escollir la informació que retornarà una determinada operació del servei. Es poden especificar com a paràmetres individuals o en un únic paràmetre p (forma compacta).

Per conèixer els paràmetres generals disponibles per a qualsevol servei, consulteu la documentació de les APIs de l'Idescat.

1.2.1. Operació cerca

L'operació cerca es pot invocar sense emprar cap paràmetre específic (resultats no filtrats). En aquest cas, retornarà les rectificacions més antigues.

Ex. 1: Llista de rectificacions més antigues en format JSON i codificació ISO-8859-1
https://api.idescat.cat/rectificacions/v1/cerca.json?enc=iso-8859-1

Per accedir a rectificacions més recents cal utilitzar el paràmetre desc (o el paràmetre posicio).

1.2.1.1. posicio

Com algunes cerques poden retornar un nombre molt elevat de resultats, la resposta no sempre els inclourà tots. El paràmetre posicio permet especificar quin ha de ser el primer resultat inclòs a la resposta. Per defecte, posicio és igual a zero.

Ex. 2: Llista a partir de la rectificació 21
https://api.idescat.cat/rectificacions/v1/cerca.xml?posicio=20

Els elements de la resposta opensearch:totalResults i opensearch:itemsPerPage permeten determinar si s'estan mostrant tots els resultats o no.

1.2.1.2. id

Quan no va acompanyat del paràmetre scheme (vegeu l'apartat següent), el paràmetre id permet seleccionar la informació d'una rectificació individual.

Ex. 3: Informació de la rectificació amb l'identificador 27
https://api.idescat.cat/rectificacions/v1/cerca.xml?id=27
1.2.1.3. scheme

Aquest paràmetre, acompanyat del paràmetre id, permet filtrar els resultats per alguna de les categories emprades en la categorització de les rectificacions. Per conèixer els criteris de categorització, utilitzeu l'operació categories.

El paràmetre scheme s'utilitza per seleccionar el criteri i el paràmetre id s'utilitza per seleccionar la categoria.

Ex. 4: Llista de rectificacions de la categoria treball ("treba") de la classificació segons "tema"
https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema&id=treba

Per incloure més d'una categoria, s'utilitzarà la coma.

Ex. 5: Llista de rectificacions amb la categoria treball ("treba") o amb la categoria turisme ("turis") de la classificació segons "tema"
https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema&id=treba,turis

Per filtrar simultàniament segons dos criteris s'utilitzarà "+" en el paràmetre scheme i id:

Ex. 6: Llista de rectificacions amb estadística ("estad") igual a "afi" i amb "tema" igual a treball ("treba") o a turisme ("turis")
https://api.idescat.cat/rectificacions/v1/cerca.xml?scheme=tema+estad&id=treba,turis+afi
1.2.1.4. published i updated

Aquests paràmetres filtren els resultats segons un període temporal: segons la data en la qual es va publicar la informació abans de ser rectificada (published) i segons la data en la qual es va produir la rectificació (updated). Cal especificar almenys un dia, mes i any en format AAAAMMDD.

Ex. 7: Llista de rectificacions des de l'1 de gener del 2010 fins a l'actualitat
https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20100101

Per definir un interval, s'utilitzarà un guió.

Ex. 8: Llista de rectificacions des de l'1 al 31 de gener del 2010 (ambdòs inclosos)
https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20100101-20100131

El guió es pot emprar per seleccionar les rectificacions d'un determinat dia.

Ex. 9: Llista de rectificacions del dia 8 d'octubre del 2010
https://api.idescat.cat/rectificacions/v1/cerca.xml?updated=20101008-20101008
1.2.1.5. orderby i desc

Per defecte, els resultats es mostren en ordre ascendent de data de la rectificació (updated). Els paràmetres orderby i desc permeten modicar aquest criteri d'ordenació.

  • orderby
    • updated: Ordenat segons la data de la rectificació. És el valor per defecte.
    • published: Ordenat segons la data de publicació de la informació abans de ser rectificada.
    • title: Ordenat segons la denominació de la informació afectada per la rectificació. Aquesta ordenació depèn de l'idioma.
    • tema: Ordenat segons el text descriptiu del tema de la rectificació. Aquesta ordenació depèn de l'idioma.
    • estad: Ordenat segons l'identificador de l'estadística.
  • desc
    • 0: Ordre ascendent. És el valor per defecte.
    • 1: Ordre descendent.

1.2.2. Operació categories

L'operació categories es pot invocar sense emprar cap paràmetre específic per obtenir els identificadors dels criteris de categorització de la informació.

Ex. 10: Llista de criteris de categorització de les rectificacions en format PHP serialitzat
https://api.idescat.cat/rectificacions/v1/categories.php

Els identificadors retornats es poden utilitzar com a paràmetre id (vegeu el següent apartat) per obtenir les seves categories.

1.2.2.1. id

Per obtenir les categories emprades en un determinat criteri, s'utilitzarà el paràmetre id.

Ex. 11: Llista de categories del criteri "tema" en format XML
https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema

1.3. Invocació sense operació

Com en el cas d'altres APIs, aquesta també admet peticions amb una sintaxi que no requereix especificar operacions (categories i cerca, en aquest cas; vegeu, a la documentació general de les APIs de l'Idescat, l'apartat 1.4. Invocació sense operació). Els avantatges d'aquest tipus d'invocació, però, són menys clars que en altres APIs perquè no suposa una simplificació significativa de les crides, ja que cal a definir igualment dues classes de recursos (categories i rectificacions).

  • Llista de criteris de categorització de les rectificacions en format XML
    https://api.idescat.cat/rectificacions/v1/categories.xml
  • Llista de categories del criteri "tema" en format JSON
    https://api.idescat.cat/rectificacions/v1/categories/tema.json
  • Llista de rectificacions del dia 8 d'octubre del 2010 en format PHP serialitzat
    https://api.idescat.cat/rectificacions/v1/rectificacions.php?updated=20101008-20101008
  • Llista de rectificacions de la categoria treball ("treba") de la classificació segons "tema" en format XML
    https://api.idescat.cat/rectificacions/v1/rectificacions.xml?scheme=tema&id=treba
  • Informació de la rectificació amb l'identificador 27 en format XML
    https://api.idescat.cat/rectificacions/v1/rectificacions/27.xml

2. Resposta

Per conèixer els codis de resposta HTTP retornats i els formats suportats per qualsevol servei, consulteu l'apartat 2 de les APIs de l'Idescat.

L'API de Rectificacions utilitza, per descriure la informació, l'estàndard Atom, ja es tracti de llistes de rectificacions (operació cerca) com de criteris de categorització o categories (operació categories).

2.1. Operació cerca

L'operació cerca utilitza, per descriure les rectificacions, l'estàndard Atom enriquit amb elements de l'estàndard OpenSearch. Consulteu la documentació d'aquests estàndards per conèixer l'estructura de la resposta de l'operació cerca: aquí només es documenten alguns elements fills de l'element entry que tenen un ús especial.

2.1.1. title

L'operació cerca utilitza l'element title per especificar la informació afectada per la rectificació.

Ex. 12: Element title
<entry>
   <title xml:lang="ca">Atur registrat</title>
   ...
</entry>

2.1.2. published i updated

L'operació cerca utilitza l'element published per especificar la data en la qual es va publicar la informació abans de ser rectificada i l'element updated per a la data en la qual es va produir la rectificació.

Ex. 13: Elements published i updated
<published>2009-01-10</published>
<updated>2010-02-15</updated>

2.1.3. content

L'operació cerca inclou la descripció de la rectificació a l'element content en format XHTML.

Ex. 14: Element content
<content xml:lang="ca" type="xhtml">
   <div xmlns="http://www.w3.org/1999/xhtml">
      ...
   </div>
</content>

2.1.4. link

Els enllaços a les pàgines afectades per la rectificació s'inclouen en elements link amb atribut rel igual a via. L'atribut title s'utilitza per oferir una descripció de la pàgina afectada en l'idioma sol·licitat.

Ex. 15: Elements link amb rel igual a via
<link
   rel="via"
   xml:lang="ca"
   type="text/html"
   href="https://www.idescat.cat/pub/?id=lma&amp;n=8.3.1.1"
   title="Persones de 16 anys i més que estan a favor de prendre mesures
            per a la protecció del medi ambient. Per àmbits territorials i tipus de mesura"
/>
<link
   rel="via"
   xml:lang="ca"
   type="text/html"
   href="https://www.idescat.cat/pub/?id=lma&amp;n=8.3.1.2"
   title="Persones de 16 anys i més que estan a favor de prendre mesures
            per a la protecció del medi ambient. Per dimensió del municipi i tipus de mesura"
/>

2.1.5. category

L'operació cerca classifica els diferents resultats utilitzant elements category. L'atribut scheme indica el criteri de categorització amb la petició a l'API que retorna la seva llista de categories possibles (vegeu l'apartat 2.2.). L'atribut term indica l'identificador de la categoria. L'atribut label inclou un literal descriptiu de la categoria en l'idioma de la petició.

Ex. 16: Elements category
<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema"
   term="xifpo"
   label="Xifres de població"
   xml:lang="ca"
/>
<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=estad"
   term="ep"
   label="Estimacions de població"
   xml:lang="ca"
/>
<category
   scheme="https://api.idescat.cat/rectificacions/v1/categories.xml?id=servei"
   term="anuals"
   label="Indicadors anuals"
   xml:lang="ca"
/>

2.2. Operació categories

L'operació categories utilitza, per exposar la categorització de les rectificacions, l'estàndard Atom. Consulteu la documentació d'aquest estàndard per conèixer l'estructura de la resposta de l'operació categories: aquí només es documenten alguns elements fills de l'element entry que tenen un ús especial.

2.2.1. title

Quan l'operació categories s'invoca sense paràmetre id (llista de criteris de categorització), l'element title de cada entry inclou l'identificador del criteri de categorització.

Ex. 17: Element title en una invocació sense id
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="ca">Temes</content>
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema"
    type="application/atom+xml"
  />
  <updated>2010-10-15</updated>
</entry>

Quan l'operació categories s'invoca amb paràmetre id (llista de categories del criteri seleccionat), l'element title de cada entry inclou l'identificador de la categoria.

Ex. 18: Element title en una invocació amb id igual a "tema"
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema/macro</id>
  <title>macro</title>
  <content xml:lang="ca">Macromagnituds</content>
  <updated>2011-09-15</updated>
</entry>

2.2.2. link

Quan l'operació categories s'invoca sense paràmetre id (llista de criteris de categorització), l'element link de cada entry inclou en el seu atribut href la petició a l'API de la llista de categories del criteri especificat a l'element title de l'entry.

Ex. 19: Element link en una invocació sense id
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="ca">Temes</content>
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

Quan l'operació categories s'invoca amb paràmetre id (llista de categories del criteri seleccionat), l'element link no apareix.

2.2.3. content

Quan l'operació categories s'invoca sense paràmetre id (llista de criteris de categorització), l'element content inclou el literal associat a l'identificador del criteri de categorització que apareix a l'element title.

Ex. 20: Element content en una invocació sense id
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="ca">Temes</content >
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

Aquest mateix literal apareix dins l'element title fill de feed quan l'operació categories s'invoca amb id.

Ex. 21: Element title fill de feed en una invocació amb id igual a "tema"
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title xml:lang="ca">Temes</title>
  <category term="1" />
  ...
</feed>

Quan l'operació categories s'invoca amb paràmetre id (llista de categories del criteri seleccionat), l'element content inclou el literal associat a l'identificador de la categoria que apareix a l'element title.

Ex. 22: Element content en una invocació amb id igual a "tema"
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema/macro</id>
  <title>macro</title>
  <content xml:lang="ca">Macromagnituds</content>
  <updated>2011-09-15</updated>
</entry>

2.2.4. category

L'operació categories utilitza l'atribut term de l'element category per expressar si ha d'aparèixer una categoria, i només una, del criteri en qüestió per a cada rectificació ("1"), si ha d'aparèixer com a mínim una però poden aparèixer més ("+"), si en poden aparèixer més d'una però també cap ("*") o si la categoria ha de ser única però pot no haver-n'hi cap ("?").

Quan l'operació categories s'invoca sense paràmetre id (llista de criteris de categorització), l'element category s'associa a cada element entry.

Ex. 23: Element category en una invocació sense id
<entry>
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title>tema</title>
  <content xml:lang="ca">Temes</content >
  <category term="1" />
  <link
    rel="alternate"
    href="https://api.idescat.cat/rectificacions/v1/categories.xml?id=tema"
    type="application/atom+xml"
  />
  <updated>2018-05-23</updated>
</entry>

Quan l'operació categories s'invoca amb paràmetre id (llista de categories del criteri seleccionat), l'element category s'associa a l'element feed.

Ex. 24: Element category fill de feed en una invocació amb id igual a "tema"
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>tag:idescat.cat,2010:rectificacions/categories/tema</id>
  <title xml:lang="ca">Temes</title>
  <category term="1" />
  ...
</feed>

2.3. Errors

Les APIs de l'Idescat utilitzen codis de resposta normalitzats per indicar si la petició ha tingut èxit o si ha fracassat.