# @giphy/js-fetch-api

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

Latest version **5.8.0** (published 2026-05-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @giphy/js-fetch-api
pnpm add @giphy/js-fetch-api
yarn add @giphy/js-fetch-api
bun add @giphy/js-fetch-api
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.8.0 |
| Published | 2026-05-01 |
| First published | 2019-03-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 76.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 167 |
| Maintainers | giphy |

## Links

- npm: https://www.npmjs.com/package/@giphy/js-fetch-api
- Repository: https://github.com/Giphy/giphy-js
- Homepage: https://github.com/Giphy/giphy-js/tree/master/packages/fetch-api
- Issues: https://github.com/Giphy/giphy-js/issues
- npm.io page: https://npm.io/package/@giphy/js-fetch-api

## Dependencies (2)

- [@giphy/js-util](https://npm.io/package/@giphy/js-util.md) *
- [@giphy/js-types](https://npm.io/package/@giphy/js-types.md) *

## Recent versions

- 5.8.0 (latest) — 2026-05-01
- 0.0.0-hidden-gifs-20250701132558 (hidden-gifs) — 2025-07-01
- 0.0.0-moat-testing-20240502211419 (moat-testing) — 2024-05-02
- 5.5.0-charlie.0 (charlie) — 2024-04-24
- 5.5.0-beta.1 (beta) — 2024-04-24
- 0.0.0-canary-20230621031504 (canary) — 2023-06-21
- 5.7.0 — 2025-07-08
- 0.0.0-hidden-gifs-20250630203509 — 2025-06-30
- 0.0.0-hidden-gifs-20250630195445 — 2025-06-30
- 0.0.0-hidden-gifs-20250626195055 — 2025-06-26
- 5.6.0 — 2024-05-28
- 5.5.0 — 2024-05-03
- 5.5.0-beta.0 — 2024-04-23
- 5.4.0 — 2024-02-22
- 5.3.0 — 2024-01-04
- … 77 more at https://npm.io/package/@giphy/js-fetch-api/versions

## README

# @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/

```typescript
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:

[![Edit @giphy/js-fetch-api](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/20kmp3zp9r?fontsize=14)

# Fetch GIFs, Stickers, and Animated Text

## _search_

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

##### Signature:

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

##### Search Options:

| option | type   | description                                     | default |
| :----- | :----- | :---------------------------------------------- | :-----: |
| _lang_ | string | See list of supported languages [here][lang].   |   en    |
| _sort_ | number | Specifies the starting position of the results. | recent  |

> Other Options: [Type Option](#type-option), [Rating Option](#rating-option), [Pagination Options](#pagination-options)

##### Example:

```typescript
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:

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

> Trending Options: [Type Option](#type-option), [Rating Option](#rating-option), [Pagination Options](#pagination-options)

##### Example:

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

## _gif by id_

Fetch a gif by id

##### Signature:

```typescript
gif(id: string): Promise<GifResult>
```

##### Example:

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

## _gifs by ids, or category and subcategory_

##### Signature:

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

##### Example:

```typescript
// 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](https://developers.giphy.com/dashboard/)

##### Signature:

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

> Options: [Pagination Options](#pagination-options)

##### Example:

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

## _related_

Fetch related gifs based on the id of a gif

##### Signature:

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

> Options: [Pagination Options](#pagination-options), [Type Option](#type-option)

##### Example:

```typescript
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:

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

> Emoji Options: [Pagination Options](#pagination-options)

##### Example:

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

## _emoji default variations_

Returns a list of all the default emoji variations.

##### Signature:

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

> Options: [Pagination Options](#pagination-options)

##### Example:

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

## _emoji variations_

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

##### Signature:

```typescript
emojiVariations(id: GifID): Promise<NonPaginatedGifsResult>
```

##### Example:

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

## _random_

Returns a random single GIF

##### Signature:

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

##### Random Options:

| option | type   | description                         |  default  |
| :----- | :----- | :---------------------------------- | :-------: |
| _tag_  | string | The GIF tag to limit randomness by. | undefined |

> Options: [Type Option](#type-option)

##### Example:

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

# Fetch Categories and Subcategories

## _categories_

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

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

Options: [Pagination Options](#pagination-options)

## _subcategories_

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

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

Options: [Pagination 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   |

[lang]: https://developers.giphy.com/docs/#language-support

---
_Source: https://npm.io/package/@giphy/js-fetch-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._