oembed gem

A slim library to work with oEmbed format.

View the Project on GitHub soulim/oembed

oembed gem

Build Status Code Climate

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

oembed gem is a simple to use and slim (~150 LOC) library to work with oEmbed format. It has no external dependencies at runtime. All you need to have is Ruby itself.

The library shares a behaviour of oEmbed client with any Ruby object. Just include Oembed::Client into that object and you are good to go.

oembed gem is provider agnostic. It has no pre-configured providers. You can build a client for any oEmbed provider of the world :)


Add this line to your application's Gemfile:

gem 'oembed'

And then execute:

$ bundle

Or install it yourself as:

$ gem install oembed


You have to do a few things to build an oEmbed client with oembed gem.

Lets start with a simple example. It will be a client for the awesome Speaker Deck. Note that we call the service class NameApi - this is to avoid clashing with gems (such as twitter) that may have classes named after the service.

require 'oembed'

class SpeakerDeckApi
  include Oembed::Client

  # Read more about endpoint on https://speakerdeck.com/faq#oembed
  def endpoint_uri

That's it. Now you can use a method #fetch to get data from oEmbed enpoint of Speaker Deck.

client = SpeakerDeckApi.new

The method #fetch will return a hash with oEmded data.

  "type" => "rich",
  "version" => 1.0,
  "provider_name" => "Speaker Deck",
  "provider_url" => "https://speakerdeck.com/",
  "title" => "Локализация приложения на базе Rails. Личный опыт и советы",
  "author_name" => "Alex Soulim",
  "author_url" => "https://speakerdeck.com/u/soulim",
  "html" => "<iframe style=\"border:0; padding:0; margin:0; background:transparent;\" mozallowfullscreen=\"true\" webkitallowfullscreen=\"true\" frameBorder=\"0\" allowTransparency=\"true\" id=\"presentation_frame_4fd3874cebb4b2001f0277e5\" src=\"//speakerdeck.com/embed/4fd3874cebb4b2001f0277e5\" width=\"710\" height=\"596\"></iframe>\n",
  "width" => 710,
  "height" => 596

oembed gem supports JSON and XML response formats. Here is an example of client for XML endpoint.

require 'oembed'

class FlickrApi
  include Oembed::Client

  def endpoint_uri

client = FlickrApi.new

It will return:

  "author_name"=>"Alex Soulim", "author_url"=>"http://www.flickr.com/photos/alex_soulim/",
  "license"=>"All Rights Reserved",

You can make requests with additional parameters. Let's build a client for Instagram and use :maxwidth parameter.

require 'oembed'

class InstagramApi
  include Oembed::Client

  def endpoint_uri

client = InstagramApi.new
client.fetch('http://instagr.am/p/BUG/', maxwidth: 300)

If you need to always customise the fetch with additional parameters this can be done by providing a fetch method in the service class. In this example we are adding a maxwidth parameter to the request.

require 'oembed'

class YoutubeApi
  include Oembed::Client

  def endpoint_uri

  def fetch(url, options={})
    super url, options.merge(maxwidth: 620)

client = YoutubeApi.new


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Supported Ruby versions

This library is tested against the following Ruby implementations: