tenor-api-js

tenor-api-js

A Lightweight JavaScript wrapper library for the Tenor API.

TenorAPI.JS is a tool used to access the TenorAPI from anywhere using NodeJS. This package supports both CommonJS and ESM.

• How to install the package
• How to use the package
• Examples
• API references

Features

• 🔍 Find GIFs using terms or phrases from Tenor.searchByQuery()
• 🔢 Know the GIF's ID? You can search using that instead using Tenor.searchByID()
• ❤️‍🔥 View Trending GIFs on Tenor from Tenor.trending()

Installation

You can install the package simply by do the following for NPM:

npm install tenor-api-js@latest

or if you wish to use Yarn instead, do this:

yarn add tenor-api-js@latest

Usage

To use this package you will require an API key from Tenor, you can get one from https://developers.google.com/tenor/guides/quickstart

import TenorAPI from 'tenor-js';
const tenor = new TenorAPI('YOUR-API-KEY');

// or with options
const tenor = new TenorAPI('YOUR-API-KEY', {
  locale: 'en', // The language to interpet the search string
  contentfilter: 'low' // Specifies the content safety filter level
})

Basic Examples

Here are some examples of what you can do with this package.

// Searching for GIFs using a term/phrase, using the default options
tenor.searchByQuery('funny cats')
  .then(result => {
    // do something here...
  })
  .catch(console.error);

// or with options
tenor.searchByQuery('funny cats', { limit: 1, randomize: true })
  .then(result => {
    // do something here...
  })
  .catch(console.error);

// Searching for GIFs using terms/phrases, using the default options
tenor.searchByQuery(['funny cats', 'funny dogs'])
  .then(result => {
    // do something here...
  })
  .catch(console.error);

// or with options
tenor.searchByQuery(['funny cats', 'funny dogs'], { limit: 2, randomize: true })
  .then(result => {
    // do something here...
  })
  .catch(console.error);

API References

These parameters are used in the debug_url when searching for the GIFs, changing these options will result in deferrent responses. Endpoint URLs and Parameters from https://developers.google.com/tenor/guides/endpoints#search

• TenorAPIOptions

  • locale => Default: 'en'

    Fetches the GIFs with the selected language, note this can be overridden with SearchOptions.locale

    // All of the supported languages found on Tenor.com
    { locale: "en" | "de" | "fr" | ... }
    

  • contentFilter => Default: 'high'

    Filters all the content that will better benefit the users.

    // See https://developers.google.com/tenor/guides/content-filtering for more info
    { contentFilter: 
        "off" // (no filtering, except nudity)
        | "low" // (G, PG, PG-13)
        | "medium" // (G, PG)
        | "high" // (G only)
    }
    

• SearchOptions

  • locale => Default: 'en'

    Fetches the GIFs with the selected language, note this can be overrides the TenorAPIOptions.locale if used.

    // All of the supported languages found on Tenor.com
    { locale: "en" | "de" | "fr" | etc... }
    

  • limit => Default: 30

    Limits the amount of results collected by the wrapper.

    { limit: number }
    

  • mediaType

    FIlters the results by the provided media type. By default, it will return all formats.

    { mediaType: 'gif' | 'tinygif' | 'mp4' | 'tinymp4' | 'sticker' }
    

  • aspectRatio => Default: all

    Filters the results for GIFs with the aspect ratios that fit within the selected ranges.

    { mediaType:
        'all' // No constraints
        | 'wide' // 0.42 <= aspect ratio <= 2.36
        | 'standard' // 0.56 <= aspect ratio <= 1.78
    }