Saltar al contingut principal

Incrustacions. API RSS

Algunes pàgines de l'Idescat proporcionen contingut associat que pot ser incrustat en pàgines de tercers. Aquesta API permet saber si, associats a una determinada pàgina, existeixen aquesta mena de continguts, així com obtenir el seu codi d'incrustació. Aquesta API segueix l'estàndard oEmbed tant en les peticions com en les respostes.

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/embed/v1/oembed.{format}[?paràmetres]
Mètode HTTP GET
Formats de la resposta xml, json
Versió 1.00 (06/05/2013)
Dreceres Petició, Resposta
Operacions oembed

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. Aquest servei 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 embed.

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

1.1.2. Operacions

En l'actualitat, aquest servei només admet l'operació oembed:

https://api.idescat.cat/embed/v1/oembed{…}

1.2. Paràmetres

D'acord amb l'estàndard oEmbed, les peticions han d'especificar el paràmetre url. Opcionalment, l'estàndard també defineix dos paràmetres addicionals: maxwidth i maxheight.

L'estàndard també preveu el paràmetre format però accepta que aquesta informació formi part de l'adreça, que és l'aproximació adoptada per l'Idescat:

https://api.idescat.cat/embed/v1/oembed.json?url={…}

1.2.1. url

És un paràmetre obligatori que conté l'adreça de la pàgina web sobre la qual es vol recuperar informació incrustable.

Ex. 1: Informació del contingut incrustable associat a la pàgina de la població per sexe d'Abella de la Conca en format XML
https://api.idescat.cat/embed/v1/oembed.xml?url=https%3A%2F%2Fwww.idescat.cat%2Fpub%2F%3Fid%3Dpmh%26n%3D446%26geo%3Dmun%3A250019

1.2.2. maxheight

Aquest paràmetre opcional permet especificar en píxels l'alçada màxima del contingut incrustable.

Ex. 2: Informació del contingut incrustable de com a màxim 300 px d'alçada associat a una determinada pàgina en format JSON
https://api.idescat.cat/embed/v1/oembed.json?maxheight=300&url={…}

1.2.3. maxwidth

Aquest paràmetre opcional permet especificar en píxels l'amplada màxima del contingut incrustable.

Ex. 3: Informació del contingut incrustable de com a màxim 200px d'amplada associat a una determinada pàgina en format XML
https://api.idescat.cat/embed/v1/oembed.xml?maxwidth=200&url={…}

2. Resposta

L'estructura de la resposta segueix l'estàndard oEmbed. Aquest estàndard només suporta dos formats de resposta: XML i JSON.

Ex. 4: Exemple de resposta en format XML
<oembed>
	<version>1.0</version>
	<type>rich</type>
	<provider_name>Idescat</provider_name>
	<provider_url>https://www.idescat.cat/</provider_url>
	<width>740</width>
	<height>565</height>
	<html>&lt;iframe height="565" width="740" frameborder="0" scrolling="no" border="0" allowfullscreen="allowfullscreen" webkitallowfullscreen="webkitallowfullscreen" allowTransparency="true" src="https://api.idescat.cat/g.ifr?url=https%3A%2F%2Fwww.idescat.cat%2Fpub%2F%3Fid%3Dpmh%26n%3D446%26geo%3Dmun%3A250019&amp;lang=ca"&gt;&lt;/iframe&gt;</html>
</oembed>
Ex. 5: Exemple de resposta en format JSON
{
	"width": 740,
	"height": 565,
	"html":"\u003ciframe height=\"565\" width=\"740\" frameborder=\"0\" scrolling=\"no\" border=\"0\" allowfullscreen=\"allowfullscreen\" webkitallowfullscreen=\"webkitallowfullscreen\" allowTransparency=\"true\" src=\"https://api.idescat.cat\/g.ifr?url=https%3A%2F%2Fwww.idescat.cat%2Fpub%2F%3Fid%3Dpmh%26n%3D446%26geo%3Dmun%3A250019\u0026amp;lang=ca\"\u003e\u003c/iframe\u003e",
	"version": "1.0",
	"type": "rich",
	"provider_name": "Idescat",
	"provider_url": "https:\/\/www.idescat.cat"
}		

3. Errors

D'acord amb l'estàndard oEmbed, si la pàgina especificada en el paràmetre url no disposa de contingut associat incrustable, el servei retornarà el codi de resposta 404.