@front-stream/oembed-parser

oembed-parser

Extract oEmbed content from given URL.

Intro

oembed-parser is a part of tool sets for content builder:

• feed-reader: extract & normalize RSS/ATOM/JSON feed
• article-parser: extract main article from given URL
• oembed-parser: extract oEmbed data from supported providers

You can use one or combination of these tools to build news sites, create automated content systems for marketing campaign or gather dataset for NLP projects...

                                    ┌────────────────┐
                            ┌───────► article-parser ├──────────┐
                            │       └────────────────┘          │
┌─────────────┐   ┌─────────┴────┐                     ┌────────▼─────────┐   ┌─────────────┐
│ feed-reader ├───► feed entries │                     │ content database ├───► public APIs │
└─────────────┘   └─────────┬────┘                     └────────▲─────────┘   └─────────────┘
                            │       ┌────────────────┐          │
                            └───────► oembed-parser  ├──────────┘
                                    └────────────────┘

Demo

• Give it a try!
• Example FaaS

Install & Usage

Node.js

npm i oembed-parser

# pnpm
pnpm i oembed-parser

# yarn
yarn add oembed-parser

import { extract } from 'oembed-parser'

// with CommonJS environments
// const { extract } = require('oembed-parser')
// or specify exactly path to cjs variant
// const { extract } = require('oembed-parser/dist/cjs/oembed-parser.js')

const url = 'https://www.youtube.com/watch?v=x2bqscVkGxk'

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

Deno

import { extract } from 'https://esm.sh/oembed-parser'

(async () => {
  const data = await extract('https://www.youtube.com/watch?v=x2bqscVkGxk')
  console.log(data)
})();

View more examples.

Deta cloud

For Deta devs please refer the source code and guideline here or simply click the button below.

APIs

.extract()

Load and extract oembed data.

Syntax

extract(String url)
extract(String url, Object params)
extract(String url, Object params, Object fetchOptions)

Parameters

url required

URL of a valid oEmbed resource, e.g. https://www.youtube.com/watch?v=x2bqscVkGxk

params optional

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.

fetchOptions optional

You can use this param to set request headers to fetch.

For example:

import { extract } from 'oembed-parser'

const url = 'https://codepen.io/ndaidong/pen/LYmLKBw'
extract(url, null, {
  headers: {
    'user-agent': 'Opera/9.60 (Windows NT 6.0; U; en) Presto/2.1.1'
  }
})

You can also specify a proxy endpoint to load remote content, instead of fetching directly.

For example:

import { extract } from 'oembed-parser'

const url = 'https://codepen.io/ndaidong/pen/LYmLKBw'
extract(url, null, {
  headers: {
    'user-agent': 'Opera/9.60 (Windows NT 6.0; U; en) Presto/2.1.1'
  },
  proxy: {
    target: 'https://your-secret-proxy.io/loadJson?url=',
    headers: {
      'Proxy-Authorization': 'Bearer YWxhZGRpbjpvcGVuc2VzYW1l...'
    }
  }
})

With the above setting, request will be forwarded to https://your-secret-proxy.io/loadJson?url={OEMBED_ENDPOINT}.

.setProviderList()

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

Syntax

setProviderList(Array providers)

Parameters

providers required

List of providers to apply.

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)

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

If you want to modify providers list, please make pull request on iamcal/oembed then create issue/pr here to ask for sync.

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/

License

The MIT License (MIT)

---