oembed-parser

Extract oEmbed content from given URL.

Demo

• Give it a try!
• Example FaaS

Setup

• Node.js

  npm i oembed-parser
  
  # pnpm
  pnpm i oembed-parser
  
  # yarn
  yarn add oembed-parser
  

Usage

import { extract } from 'oembed-parser'

// with CommonJS environments
// const { extract } = require('oembed-parser/dist/cjs/oembed-parser.js')

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:

import { extract } from '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 can be useful when you want to specify some additional customizations.

Here are several popular params:

• maxwidth: max width of embed size
• maxheight: max height of embed size
• theme: e.g, dark or light
• lang: e.g, 'en', 'fr', 'cn', 'vi', etc

Note that some params are supported by these providers but not by the others. Please see the provider's oEmbed API docs carefully for exact information.

.hasProvider(String URL)

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

Examples:

import { hasProvider } from '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:

import { findProvider } from '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:

import { setProviderList } from '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.

.getRequestOptions()

Return current request options.

Default values can be found here.

Facebook and Instagram

In order to work with the links from Facebook and Instagram, you need a reviewed Facebook's app with oEmbed Read permission.

When seeing a link from Facebook or Instagram, oembed-parser will look for environment variables FACEBOOK_APP_ID and FACEBOOK_CLIENT_TOKEN to retrieve oembed data using your app credentials.

For example:

export FACEBOOK_APP_ID=your_app_id
export FACEBOOK_CLIENT_TOKEN=your_client_token

npm run eval https://www.instagram.com/tv/CVlR5GFqF68/

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)