oEmbed Documentation

The oEmbed standard makes it easy to create an embed by just providing a URL to the publication. Read more on http://oembed.com This document describes how the Issuu oEmbed API endpoint is used.

Configuration

URL scheme:

https://issuu.com/*/docs/*

API endpoint:

https://issuu.com/oembed

Request

The Issuu oEmbed service accepts HTTPS GET requests with the following query parameters:

| Name           | Data type | Description                                   |
|----------------|-----------|-----------------------------------------------|
| url (required) | string    | Issuu publication URL. May contain additional |
|                |           | custom parameters:                            |
|                |           | e - supply embed id, used for customization   |
|                |           | options                                       |
| iframe         | string    | Enforce an iframe version of the embed.       |
| maxwidth       | integer   | Maximum embed width in pixels.                |
| maxheight      | integer   | Maximum embed height in pixels.               |
| format         | string    | Required response format (json/xml)           |

Example:

https://issuu.com/oembed?url=https%3A%2F%2Fissuu.com%2Fiscience%2Fdocs%2Fissue23&format=json

You can request an iframe version of Issuu embed code by specifying iframe=true when invoking the endpoint:

https://issuu.com/oembed?url=https%3A%2F%2Fissuu.com%2Fiscience%2Fdocs%2Fissue23&iframe=true&format=json

If you own the publication on Issuu and are paying for the Premium plan, you can use customization options by using the link provided when creating the embed from My Publications which contains the the e parameter (?e=xxxx/yyyy):

https://issuu.com/oembed?url=https%3A%2F%2Fissuu.com%2Fiscience%2Fdocs%2Fissue23%3Fe%3D1064136%252F7680915&format=json

Response

The oEmbed response is either JSON or XML, based on the value of the format request parameter. Default response format is JSON.

JSON response

JSON responses are using a mime-type of application/json and contain well formed JSON objects.

XML response

XML responses are using a mime-type of text/xml and contain well formed XML documents.

Example responses

XML

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<oembed>
  <version>1.0</version>
  <type>rich</type>
  <width>525</width>
  <height>323</height>
  <title>I, Science - Issue 23 (Winter 2012/13)</title>
  <url>https://issuu.com/iscience/docs/issue23</url>
  <author_name>iscience</author_name>
  <author_url>https://issuu.com/iscience</author_url>
  <provider_name>issuu</provider_name>
  <provider_url>https://issuu.com</provider_url>
  <html>&lt;div data-url=&quot;https://issuu.com/iscience/docs/issue23&quot; style=&quot;width: 525px; height: 323px;&quot; class=&quot;issuuembed&quot;&gt;&lt;/div&gt;&lt;script type=&quot;text/javascript&quot; src=&quot;//e.issuu.com/embed.js&quot; async=&quot;true&quot;&gt;&lt;/script&gt;&lt;/html&gt;
</oembed>

JSON

{
  "version": "1.0",
  "type": "rich",
  "width": 525,
  "height": 323,
  "title": "I, Science - Issue 23 (Winter 2012/13)",
  "url": "https://issuu.com/iscience/docs/issue23",
  "author_name": "iscience",
  "author_url": "https://issuu.com/iscience",
  "provider_name": "issuu",
  "provider_url": "https://issuu.com",
  "html": "<div data-url=\"https://issuu.com/iscience/docs/issue23\" style=\"width: 525px; height: 323px;\" class=\"issuuembed\"></div><script type=\"text/javascript\" src=\"//e.issuu.com/embed.js\" async=\"true\"></script>"
}

oEmbed discovery

Issuu supports oEmbed discovery for all publications on issuu.com website. Every Issuu publication page contains two discovery links that are pointing to the API endpoint and enable consumers to fetch the oEmbed data in JSON or XML format.

<link rel="alternate" type="application/json+oembed" href="https://issuu.com/oembed?url=https%3A%2F%2Fissuu.com%2Fiscience%2Fdocs%2Fissue23&format=json" title="I, Science - Issue 23 (Winter 2012/13)">
<link rel="alternate" type="text/xml+oembed" href="https://issuu.com/oembed?url=https%3A%2F%2Fissuu.com%2Fiscience%2Fdocs%2Fissue23&format=xml" title="I, Science - Issue 23 (Winter 2012/13)">