Using oEmbed for integration
Flourish supports oEmbed, a widely-used open standard for embedding content from third party platforms. oEmbed can be used as an alternative to our embed scripts or iframes, and is particularly useful in the context of content management systems, which often prohibit authors from inputting arbitrary markup like script tags.
In a typical implementation, the author will enter a URL identifying a resource into their CMS, and the CMS will use oEmbed to fetch the correct markup, substituting it for the URL when the page is rendered.
Endpoint and schemes
The Flourish oEmbed endpoint is https://app.flourish.studio/api/v1/oembed
.
Flourish supports two oEmbed schemes: https://public.flourish.studio/visualisation/*
for visualizations and https://public.flourish.studio/story/*
for stories.
We only support json
format. Specifying format=xml
will return an error.
The optional maxheight
and maxwidth
parameters can be used to specified the preferred size of the embed.
Example
The author enters the URL of a Flourish visualization, e.g https://public.flourish.studio/visualisation/2038977
.
As this URL matches one of our schemes, your application can make an oEmbed query by escaping it and passing at as the url
parameter to our oEmbed endpoint:
GET https://app.flourish.studio/api/v1/oembed?url=https%3A%2F%2Fpublic.flourish.studio%2Fvisualisation%2F2038977%2F
which will return the following response:
{
"type":"rich",
"version":"1.0",
"provider_name":"Flourish",
"provider_url":"https://flourish.studio",
"html":"<iframe src=\"https://flo.uri.sh/visualisation/2038977/embed\" frameborder=\"0\" scrolling=\"no\" height=\"575\" width=\"700\" style=\"width:100%;\"></iframe>",
"width":700,
"height":575
}
Your application can then insert the provided html
markup into its output.