oembed-parser

oembed-parser

Extract eEmbed content from given URL.

Demo

• Give it a try!
• Example FaaS

Installation

$ npm install oembed-parser

# or pnpm
$ pnpm install oembed-parser

# or yarn
$ yarn add oembed-parser

Usage

const { extract } = require('oembed-parser')

// es6 module syntax
import { extract } from 'oembed-parser'

// test
const url = 'https://www.youtube.com/watch?v=8jPQjjsBbIc'

extract(url).then((oembed) => {
  console.log(oembed)
}).catch((err) => {
  console.trace(err)
})

APIs

.extract(String url [, Object params])

Load and extract oembed data.

Example:

const { extract } = require('oembed-parser')

const getOembed = async (url) => {
  try {
    const oembed = await extract(url)
    return oembed
  } catch (err) {
    console.trace(err)
  return null
  }
}

const data = getOembed('your url')
console.log(data)

Optional argument params is an object with it we can set maxwidth and/or maxheight those are used to scale embed size to fit your container size. Please refer oEmbed/Full Spec/Consumer Request for more info.

.hasProvider(String URL)

Check if a URL matches with any provider in the list.

Examples:

const { hasProvider } = require('oembed-parser')

hasProvider('https://www.youtube.com/watch?v=ciS8aCrX-9s') // return true
hasProvider('https://trello.com/b/BO3bg7yn/notes') // return false

.findProvider(String URL)

Get the provider which is relevant to given URL.

For example:

const { findProvider } = require('oembed-parser')

findProvider('https://www.facebook.com/video.php?v=999999999')

Result looks like below:

{
  fetchEndpoint: 'https://graph.facebook.com/v10.0/oembed_video',
  providerName: 'Facebook',
  providerUrl: 'https://www.facebook.com/'
}

.setProviderList(Array providers)

Apply a list of providers to use, overriding the default.

This can be useful for whitelisting only certain providers, or for adding custom providers.

Default list of resource providers is synchronized from oembed.com.

For example:

const { setProviderList } = require('oembed-parser')

const providers = [
  {
    provider_name: 'Alpha',
    provider_url: 'https://alpha.com',
    endpoints: [
      // endpoint definition here
    ]
  },
  {
    provider_name: 'Beta',
    provider_url: 'https://beta.com',
    endpoints: [
      // endpoint definition here
    ]
  }
]

setProviderList(providers)

.setRequestOptions(Object requestOptions)

Define options to call oembed HTTP request.

oembed-parser is using axios to send HTTP requests. Please refer axios' request config for more info.

Default option:

{
  headers: {
    'user-agent': 'Mozilla/5.0 (X11; Linux i686; rv:94.0) Gecko/20100101 Firefox/94.0',
    accept: 'application/json; charset=utf-8'
  },
  responseType: 'json',
  responseEncoding: 'utf8',
  timeout: 6e4,
  maxRedirects: 3
}

Facebook and Instagram

Since October 24 2020, Facebook have deprecated their legacy urls and applied a new Facebook oEmbed endpoints.

Technically, now we have to use Facebook Graph API, with the access token from a valid and live Facebook app. oembed-parser will try to get these values from environment variables, so please define them, for example:

export FACEBOOK_APP_ID=your_app_id
export FACEBOOK_CLIENT_TOKEN=your_client_token

References:

• oEmbed Read
• Facebook oEmbed
• Facebook Graph API

Test

git clone https://github.com/ndaidong/oembed-parser.git
cd oembed-parser
npm install
npm test

# quick evaluation
npm run eval {URL_TO_PARSE_OEMBED}

License

The MIT License (MIT)