jonathanfann/giphy-api

Node.js Giphy.com API

giphy-api

Simple to use Node.js module for the giphy.com API that supports promises and callbacks. All search parameters and endpoints can be found on the Giphy API documentation.

Installation

npm install giphy-api --save

Requiring

// Require with custom API key
var giphy = require('giphy-api')('API KEY HERE');
// Require with the public beta key
var giphy = require('giphy-api')();

Initialization Options

var giphy = require('giphy-api')({
    ...
});

• https {Boolean} - Whether to utilize HTTPS library for requests or HTTP. Defaults to HTTP.
• timeout {Number} - Maximum timeout of an API request. Defaults to 30 seconds.
• apiKey {String} - Giphy API key. Defaults to API beta key

Phrase search

Search all Giphy GIFs for a word or phrase. Supported parameters:

• q - search query term or phrase
• limit - (optional) number of results to return, maximum 100. Default 25.
• offset - (optional) results offset, defaults to 0.
• rating - limit results to those rated (y,g, pg, pg-13 or r).
• fmt - (optional) return results in html or json format (useful for viewing responses as GIFs to debug/test)

// Search with a plain string using callback
giphy.search('pokemon', function(err, res) {
    // Res contains gif data!
});

// Search with options using promise
giphy.search('pokemon').then(function(res) {
    // Res contains gif data!
});

// Search with options using callback
giphy.search({
    q: 'pokemon',
    rating: 'g'
}, function(err, res) {
    // Res contains gif data!
});

Giphy Id search

Search all Giphy gifs for a single Id or an array of Id's

//Search with a single Id using callback
giphy.id('feqkVgjJpYtjy', function(err, res) {

});

//Search with a single Id using promise
giphy.id('feqkVgjJpYtjy').then(function(res) {

});

// Search with an array of Id's
giphy.id([
    'feqkVgjJpYtjy',
    '7rzbxdu0ZEXLy'
], function(err, res) {

});

Translate search

Experimental search endpoint for gif dialects. Supported parameters:

• s - term or phrase to translate into a GIF
• rating - limit results to those rated (y,g, pg, pg-13 or r).
• fmt - (optional) return results in html or json format (useful for viewing responses as GIFs to debug/test)

// Translate search with a plain string using callback
giphy.translate('superman', function(err, res) {

});

// Translate search with a plain string using promise
giphy.translate('superman').then(function(res) {

});

// Translate search with options
giphy.translate({
    s: 'superman',
    rating: 'g',
    fmt: 'html'
}, function(err, res) {

});

Random

Random gif(s) filtered by tag. Supported parameters:

• tag - the GIF tag to limit randomness by
• rating - limit results to those rated (y,g, pg, pg-13 or r).
• fmt - (optional) return results in html or json format (useful for viewing responses as GIFs to debug/test)

// Random gif by tag using callback
giphy.random('superman', function(err, res) {

});

// Random gif by tag using promise
giphy.random('superman').then(function(res) {

});

// Random gif with options
giphy.random({
    tag: 'superman',
    rating: 'g',
    fmt: 'json'
}, function(err, res) {

});

Trending

Trending gifs on The Hot 100 list

• limit (optional) limits the number of results returned. By default returns 25 results.
• rating - limit results to those rated (y,g, pg, pg-13 or r).
• fmt - (optional) return results in html or json format (useful for viewing responses as GIFs to debug/test)

// Trending Hot 100 gifs using callback
giphy.trending(function(err, res) {

});

// Trending Hot 100 gifs using promise
giphy.trending().then(function(res) {

});

// Trending Hot 100 gifs with options
giphy.trending({
    limit: 2,
    rating: 'g',
    fmt: 'json'
}, function(err, res) {

});

Stickers

Animated stickers are gifs with transparent backgrounds. All giphy-api functions support stickers except id, which is not a supported Giphy sticker endpoint. In order to use the sticker API instead of the gif API, simply pass the api property to a giphy-api function.

// Sticker search using callback
giphy.search({
    api: 'stickers',
    q: 'funny'
}, function(err, res) {

});

// Sticker search using promise
giphy.search({
    api: 'stickers',
    q: 'funny'
}).then(res) {

});