YouTube oembed parameters / documentation

Update Nov 2017 there now appears to be official documentation.

While looking at a bug in Umbraco, I could not find, anywhere, a definitive description of the YouTube oembed service – so I’ve decided to write one up. Please let me know if you find other features, or if this has drifted away from accuracy. Or if I’ve just been incompetent and not found the official API documentation somehow.

The YouTube oembed service is available at (note https, not http as otherwise advertised, it’s 301 redirected).

Standard parameters (as per oembed specification)

  • url – the URL of the resource
  • maxwidth – the maximum width. The thumbnail size is not affected. This value, if bigger than the usual video return, will increase the size of the video.
  • maxheight – the maximum height. The thumbnail size is not affected. This value will only decrease the size of the video.
  • format – “json” or “xml”

Non-standard parameters

  • scheme – you can set this to “https” to make the returned code work on a site served over https. (Why the returned data doesn’t use “//”, I don’t know…)


1 thought on “YouTube oembed parameters / documentation

  1. Steve Smith

    Thanks for this info. Four years on there still seems to be no official documentation for this endpoint. It may be worth noting that the scheme now defaults to ‘https’, but that parameter can be set to ‘http’ if that is what is required.


Leave a Reply