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.

Caching and freshness

Most oEmbed consumers fetch the html once, when the embed URL is first inserted, and cache it from then on. Republishing a Flourish visualisation does not make them fetch it again.

The Flourish oEmbed endpoint generates its response on every request and always returns the current html. Any staleness comes from the consumer's cache, so fetching the endpoint again returns a fresh copy.

WordPress only refreshes its cached embed HTML when the post is edited and re-saved.