Incrustaciones. API 
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.
| 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 |
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><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&lang=es"></iframe></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.