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.
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
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><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=en"></iframe></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.