A slim library to work with oEmbed format.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib Bump version Aug 16, 2016
spec Add a test to show the redirect bug in action. Fix the bug. Jul 1, 2016
.rspec Init RSpec suite Aug 31, 2012
.travis.yml Drop support for Ruby 1.9.3 Aug 16, 2016
LICENSE Update my name :) Oct 30, 2014
README.md Drop support for Ruby 1.9.3 Aug 16, 2016
Rakefile Promote :spec to the default Rake task Oct 30, 2014


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.

  • include Oembed::Client into your object,
  • add instance method #endpoint_uri to that object. This method has to return a string with URI of oEmbed endpoint.

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:

  • MRI Ruby 2.1
  • MRI Ruby 2.0
  • JRuby