oembed-extractor

Extract oEmbed content from given URL.

Demo

• Give it a try!
• Example FaaS

Install & Usage

Node.js

1npm i @extractus/oembed-extractor
2
3# pnpm
4pnpm i @extractus/oembed-extractor
5
6# yarn
7yarn add @extractus/oembed-extractor

1import { extract } from '@extractus/oembed-extractor'
2
3const result = await extract('https://www.youtube.com/watch?v=x2bqscVkGxk')
4console.log(result)

Deno

1import { extract } from 'npm:@extractus/oembed-extractor'

Browser

1import { extract } from "https://esm.sh/@extractus/oembed-extractor@latest"

Please check the examples for reference.

APIs

.extract()

Load and extract oembed data.

Syntax

1extract(String url)
2extract(String url, Object params)
3extract(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

fetchOptions is an object that can have the following properties:

• headers: to set request headers
• proxy: another endpoint to forward the request to
• agent: a HTTP proxy agent
• signal: AbortController signal or AbortSignal timeout to terminate the request

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

For example:

1import { extract } from '@extractus/oembed-extractor'
2
3const url = 'https://codepen.io/ndaidong/pen/LYmLKBw'
4extract(url, null, {
5  headers: {
6    'user-agent': 'Opera/9.60 (Windows NT 6.0; U; en) Presto/2.1.1'
7  }
8})

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

For example:

1import { extract } from '@extractus/oembed-extractor'
2
3const url = 'https://codepen.io/ndaidong/pen/LYmLKBw'
4extract(url, null, {
5  headers: {
6    'user-agent': 'Opera/9.60 (Windows NT 6.0; U; en) Presto/2.1.1'
7  },
8  proxy: {
9    target: 'https://your-secret-proxy.io/loadJson?url=',
10    headers: {
11      'Proxy-Authorization': 'Bearer YWxhZGRpbjpvcGVuc2VzYW1l...'
12    }
13  }
14})

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

Another way to work with proxy is use agent option instead of proxy as below:

1import { extract } from '@extractus/oembed-extractor'
2
3import { HttpsProxyAgent } from 'https-proxy-agent'
4
5const proxy = 'http://abc:RaNdoMpasswORd_country-France@proxy.packetstream.io:31113'
6
7const url = 'https://codepen.io/ndaidong/pen/LYmLKBw'
8
9const oembed = await extract(url, null, {
10  agent: new HttpsProxyAgent(proxy),
11})
12console.log('Run oembed-extractor with proxy:', proxy)
13console.log(oembed)

For more info about https-proxy-agent, check its repo.

By default, there is no request timeout. You can use the option signal to cancel request at the right time.

The common way is to use AbortControler:

1const controller = new AbortController()
2
3// stop after 5 seconds
4setTimeout(() => {
5  controller.abort()
6}, 5000)
7
8const oembed = await extract(url, null, {
9  signal: controller.signal,
10})

A newer solution is AbortSignal's timeout() static method:

1// stop after 5 seconds
2const oembed = await extract(url, null, {
3  signal: AbortSignal.timeout(5000),
4})

For more info:

• AbortController constructor
• AbortSignal: timeout() static method

.setProviderList()

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

Syntax

1setProviderList(Array providers)

Parameters

providers required

List of providers to apply.

For example:

1import { setProviderList } from '@extractus/oembed-extractor'
2
3const providers = [
4  {
5    provider_name: 'Alpha',
6    provider_url: 'https://alpha.com',
7    endpoints: [
8      // endpoint definition here
9    ]
10  },
11  {
12    provider_name: 'Beta',
13    provider_url: 'https://beta.com',
14    endpoints: [
15      // endpoint definition here
16    ]
17  }
18]
19
20setProviderList(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:

1export FACEBOOK_APP_ID=your_app_id
2export FACEBOOK_CLIENT_TOKEN=your_client_token
3
4npm run eval https://www.instagram.com/tv/CVlR5GFqF68/

Test

1git clone https://github.com/extractus/oembed-extractor.git
2cd oembed-extractor
3npm i
4npm test

Quick evaluation

1git clone https://github.com/extractus/oembed-extractor.git
2cd oembed-extractor
3npm i
4npm run eval {URL_TO_PARSE_OEMBED}

License

The MIT License (MIT)

Support the project

If you find value from this open source project, you can support in the following ways:

• Give it a star ⭐
• Buy me a coffee: https://paypal.me/ndaidong 🍵
• Subscribe oEmbed Parser service on RapidAPI 😉

Thank you.

---