README.md

@giphy/js-fetch-api

Javascript API to fetch gifs and stickers from the GIPHY API.

Get started with your own api key: https://developers.giphy.com/docs/

import { GiphyFetch } from '@giphy/js-fetch-api'

const gf = new GiphyFetch('your api key')

// fetch 10 gifs
const { data: gifs } = await gf.trending({ limit: 10 })

Try it out:

Fetch GIFs, Stickers, and Animated Text

search

Search all Giphy GIFs for a word or phrase. Punctuation will be stripped and ignored.

Signature:

search(term: string, options?: SearchOptions): Promise<GifsResult>

Search Options:

option	type	description	default
lang	string	See list of supported languages here.	en
sort	number	Specifies the starting position of the results.	recent

Other Options: Type Option, Rating Option, Pagination Options

Example:

const { data: gifs } = await gf.search('dogs', { sort: 'relevant', lang: 'es', limit: 10, type: 'stickers' })

trending

Fetch GIFs currently trending online. Hand curated by the Giphy editorial team. The data returned mirrors the GIFs showcased on the Giphy homepage.

Signature:

trending(options?: TrendingOptions): Promise<GifsResult>

Trending Options: Type Option, Rating Option, Pagination Options

Example:

const { data: gifs } = await gf.trending({ limit: 10, offset: 25, rating: 'g' })

gif by id

Fetch a gif by id

Signature:

gif(id: string): Promise<GifResult>

Example:

const { data: gif } = await gf.gif('3oEjHGr1Fhz0kyv8Ig')

gifs by ids, or category and subcategory

Signature:

// by id
gifs(ids: string[]): Promise<GifsResult>
// by category and subcategory
gifs(category: string, subcategory: string): Promise<GifsResult>

Example:

// by id
const { data: gifs } = await gf.gifs(['3oEjHGr1Fhz0kyv8Ig'])
// by category and subcategory
const { data: gifs } = await gf.gifs('tv', 'arrested-development')

animate

Create animated text gifs dynamicaly based on the text input. This endpoint will require you to create a new SDK key

Signature:

animate(text: string, options?: PaginationOptions): Promise<GifsResult>

Options: Pagination Options

Example:

const { data: gifs } = await gf.animate('some text to animate!', { limit: 5 })

related

Fetch related gifs based on the id of a gif

Signature:

related(id: string, options?: RelatedOptions): Promise<GifsResult>

Options: Pagination Options, Type Option

Example:

const { data: gifs } = await gf.related('3oEjHGr1Fhz0kyv8Ig', { limit: 10 })

emoji

Fetch emoji. Emoji are stickers from a currated channel. There's no search or trending emoji.

Signature:

emoji(options?: PaginationOptions): Promise<GifsResult>

Emoji Options: Pagination Options

Example:

const { data: gifs } = await gf.emoji()

emoji default variations

Returns a list of all the default emoji variations.

Signature:

emojiDefaultVariations(options?: PaginationOptions): Promise<GifsResult>

Options: Pagination Options

Example:

const { data: gifs } = await gf.emojiDefaultVariations()

emoji variations

Returns a list of gifs representing all the variations for the emoji.

Signature:

emojiVariations(id: GifID): Promise<NonPaginatedGifsResult>

Example:

const { data: gifs } = await gf.emojiVariations('iigp4VDyf5dCLRlGkm')

random

Returns a random single GIF

Signature:

random(options?: RandomOptions): Promise<GifResult>

Random Options:

option	type	description	default
tag	string	The GIF tag to limit randomness by.	undefined

Options: Type Option

Example:

const { data: gif } = await gf.random({ tag: 'beer', type: 'stickers' })

Fetch Categories and Subcategories

categories

categories(options?: CategoriesOptions): Promise<CategoriesResult>

const { data: categories } = await gf.categories()
categories.forEach((category) => {
    console.log(category) // ICategory
})

Options: Pagination Options

subcategories

subcategories(category: string, options?: SubcategoriesOptions): Promise<CategoriesResult>

// Example:
const { data: categories } = await gf.subcategories('tv', { limit: 10, offset: 25, rating: 'g' })
categories.forEach((category) => {
    console.log(category) // ICategory
})

Options: Pagination Options

Shared Options

Pagination Options

option	type	description	default
limit	number	Number of results to return, maximum 100	25
offset	number	Specifies the starting position of the results.	0

Rating Option

option	type	description	default
rating	string	limit results by rating: y, g, pg, pg-13, r.	g

Type Option

option	type	description	default
type	string	gifs / stickers / text / videos	gifs