Incrustaciones. API RSS

28.06.2017

Algunas páginas del Idescat proporcionan contenido asociado que puede ser incrustado en páginas de terceros. Esta API permite saber si, asociados a una determinada página, existen este tipo de contenidos, así como obtener su código de incrustación. Esta API sigue el estándar oEmbed tanto en las peticiones como en las respuestas.

La utilización de este servicio comporta la aceptación de las condiciones de uso de las API del Idescat.

Resumen
URI base https://api.idescat.cat/embed/v1/oembed.{formato}[?parámetros]
Método HTTP GET
Formatos de la respuesta xml, json
Versión 1.00 (06.05.2013)
Atajos Petición, Respuesta
Operaciones oembed
Widgets que utilizan este servicio

1. Petición

1.1. Características básicas

Toda petición tiene que especificar obligatoriamente el servicio, la versión, la operación y el formato. Versión y operación son características específicas de cada servicio. Este servicio soporta los formatos de respuesta generales de las API del Idescat. Para más información, se puede consultar el apartado Anatomía de las peticiones en la documentación general de las API del Idescat.

1.1.1. Identificador del servicio y versión

El identificador de este servicio es embed.

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

1.1.2. Operaciones

En la actualidad, este servicio solo admite la operación oembed:

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

1.2. Parámetros

De acuerdo con el estándar oEmbed, las peticiones tienen que especificar el parámetro url. Opcionalmente, el estándar también define dos parámetros adicionales: maxwidth i maxheight.

El estándar también prevé el parámetro format pero acepta que esta información forme parte de la dirección, que es la aproximación adoptada por el Idescat:

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

1.2.1. url

Es un parámetro obligatorio que contiene la dirección de la página web sobre la cual se quiere recuperar información incrustable.

Ej. 1: Información del contenido incrustable asociado a la página de la población por sexo de Abella de la Conca en formato 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%26lang%3Des&lang=es

1.2.2. maxheight

Este parámetro opcional permite especificar en píxeles la altura máxima del contenido incrustable.

Ej. 2: Información del contenido incrustable de como máximo 300 px de altura asociado a una determinada página en formato JSON
https://api.idescat.cat/embed/v1/oembed.json?maxheight=300&url={…}

1.2.3. maxwidth

Este parámetro opcional permite especificar en píxeles la anchura máxima del contenido incrustable.

Ej. 3: Información del contenido incrustable de como máximo 200px de anchura asociado a una determinada página en formato XML
https://api.idescat.cat/embed/v1/oembed.xml?maxwidth=200&url={…}

2. Respuesta

La estructura de la respuesta sigue el estándar oEmbed. Este estándar solo soporta dos formatos de respuesta: XML y JSON.

Ej. 4: Ejemplo de respuesta en formato XML
<?xml version="1.0" encoding="utf-8" standalone="yes"?><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=es"&gt;&lt;/iframe&gt;</html>
</oembed>
Ej. 5: Ejemplo de respuesta en formato 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=es\"\u003e\u003c/iframe\u003e",
	"version": "1.0",
	"type": "rich",
	"provider_name": "Idescat",
	"provider_url": "https:\/\/www.idescat.cat"
}

3. Errores

De acuerdo con el estándar oEmbed, si la página especificada en el parámetro url no dispone de contenido asociado incrustable, el servicio devolverá el código de respuesta 404.

Usted está aquí: