Nonprofit Pizza Maker

    oembed-parser
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.4 • Public • Published

    oembed-parser

    Extract oEmbed content from given URL.

    NPM CI test Coverage Status CodeQL JavaScript Style Guide

    Demo

    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)
    })
    Note:

    Since Node.js v14, ECMAScript modules have became the official standard format. Just ensure that you are using module system and enjoy with ES6 import/export syntax.

    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.

    Default option:

    {
      headers: {
        'user-agent': 'Mozilla/5.0 (X11; Linux x86_64; rv:95.0) Gecko/20100101 Firefox/95.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:

    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)


    Install

    npm i oembed-parser

    DownloadsWeekly Downloads

    18,405

    Version

    3.0.4

    License

    MIT

    Unpacked Size

    792 kB

    Total Files

    42

    Last publish

    Collaborators

    • dongnd
    • danscan
    • kevinansfield