Embed. API

Some web pages at Idescat provide content that may be embedded in third party websites. This API shows whether content of this type exists in a certain page, and also how to obtain its embeddable code. This API follows the oEmbed standard both for requests and responses.

The use of this service involves acceptance of the terms of use of Idescat APIs.

Summary
Base URI	https://api.idescat.cat/embed/v1/oembed.{format}[?parameters]
HTTP method	GET
Response formats	xml, json
Version	1.00 (05/06/2013)
Shortcuts	Request, Response
Operations	oembed

1. Request
- 1.1. Basic characteristics
  - 1.1.1. Identifier of service and version
  - 1.1.2. Operations
- 1.2. Parameters
2. Response
3. Errors

1. Request

1.1. Basic characteristics

Every request must specify by obligation the service, version, operation and format. Version and operation are specific characteristics of each service. This service supports the general response formats for Idescat APIs. For further information, please see the Anatomy of Requests section of the general documentation on Idescat APIs.

1.1.1. Identifier of service and version

The identifier of this service is embed.

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

1.1.2. Operations

At present, this service only admits the operation oembed.

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

1.2. Parameters

In accordance with the oEmbed standard, requests must specify the parameter url. Optionally, the standard also defines two additional parameters: maxwidth and maxheight.

The standard also supports the parameter format but accepts to have the format specified as part of the address, which is the approach used by Idescat:

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

1.2.1. `url`

This is an mandatory parameter that contains the web address to retrieve embbeding information for.

Ex. 1: Information on embeddable content for the population by sex page for Abella de la Conca in XML format

https://api.idescat.cat/embed/v1/oembed.xml?url=https://api.idescat.cat/g.ifr?url=https%3A%2F%2Fwww.idescat.cat%2Fpub%2F%3Fid%3Dpmh%26n%3D446%26geo%3Dmun%3A250019%26lang%3Den&lang=en

1.2.2. `maxheight`

This optional parameter can specify the maximum height in pixels of the embeddable content.

Ex. 2: Information on embeddable content of a maximum height of 300 px associated to a certain page in JSON format

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

1.2.3. `maxwidth`

This optional parameter can specify the maximum width in pixels of the embeddable content.

Ex. 3: Information on embeddable content of a maximum width of 200px for a certain page in XML format

https://api.idescat.cat/embed/v1/oembed.xml?maxwidth=200&url={…}

2. Response

The response structure follows the oEmbed standard. This standard only supports two response formats: XML and JSON.

Ex. 4: Example response in XML format

<?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=en"&gt;&lt;/iframe&gt;</html>
</oembed>

Ex. 5:Example response in JSON format

{
	"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=en\"\u003e\u003c/iframe\u003e",
	"version": "1.0",
	"type": "rich",
	"provider_name": "Idescat",
	"provider_url": "https:\/\/www.idescat.cat"
}

3. Errors

According to the oEmbed standard, if the page specified in the parameter url has no associated embeddable content, the service will return the response code 404.