Endpoints
If you want to see these endpoints in action before getting started, you can use our API Explorer to input sample queries and view the live responses!
Trending Endpoint
GIPHY Trending returns a list of the most relevant and engaging content each and every day. Our feed of trending content is continuously updated, so you always have the latest and greatest at your fingertips.
- GIPHY requires the Trending API call be made from the client side.
- Optionally, use the &rating param to tailor the response per your preferences. Read more here about content ratings.
- Optionally, you can use rendition on demand bundles to limit which renditions the API sends.
| Gif URL | Sticker URL |
|---|---|
| api.giphy.com/v1/gifs/trending | api.giphy.com/v1/stickers/trending |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| limit: integer (int32) | 20 | The maximum number of objects to return. (Default: “25”) |
| offset: integer (int32) | 5 | Specifies the starting position of the results. Default: “0” Maximum: “499” |
| rating: string | g | Filters results by specified rating. Acceptable values include g, pg, pg-13, r. If you do not specify a rating, you will receive results from all possible ratings. |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
| bundle: string | messaging_non_clips | Returns only renditions that correspond to the named bundle. Read more about renditions. |
Successful Response (200 OK)
- data: GIF Object[]
- pagination: Pagination Object
- meta: Meta Object
Search Endpoint
GIPHY Search gives you instant access to our library of millions of GIFs and Stickers by entering a word or phrase. With our unparalleled search algorithm, users can easily express themselves and animate their conversations.
- GIPHY requires the Search API call be made from the client side.
- The search keyword should be sent to GIPHY in &q parameter in the API call. Search terms could simply be words or phrases typed by the user. Users can also add the @ sign before a GIPHY username to return content from a specific GIPHY channel. All special characters should be supported and not re-encoded in your search request.
- This keyword should be the exact terms the user searched for without any correction/enhancement
- Optionally, use the &lang parameter to indicate the language the user has typed in. This will help return unique regional content, if available. See here for supported languages.
- You may use the &rating param to tailor the response per your preferences. Read more here about content ratings
- Optionally, you can use rendition on demand bundles to limit which renditions the API sends.
| Gif URL | Sticker URL |
|---|---|
| api.giphy.com/v1/gifs/search | api.giphy.com/v1/stickers/search |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| q: string(required) | cheeseburgers | Search query term or phrase. Adding @<username> anywhere in the q parameter effectively changes the search query to be a search for a specific user’s GIFs (user has to be public and verified user by GIPHY.) If the q parameter contains one of these words: sticker, stickers, or transparent, the search will return stickers content. Maximum length: 50 chars. |
| limit: integer (int32) | 20 | The maximum number of objects to return. (Default: “25”).For beta keys max limit is 50 |
| offset: integer (int32) | 5 | Specifies the starting position of the results. Default: “0” Maximum: “4999” |
| rating: string | g | Filters results by specified rating. Acceptable values include g, pg, pg-13, r. If you do not specify a rating, you will receive results from all possible ratings. |
| lang: string | en | Specify default language for regional content; use a 2-letter ISO 639-1 language code. |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
| bundle: string | messaging_non_clips | Returns only renditions that correspond to the named bundle. Read more about renditions. |
Successful Response (200 OK)
- data: GIF Object[]
- pagination: Pagination Object
- meta: Meta Object
Translate Endpoint
GIPHY Translate converts words and phrases to the perfect GIF or Sticker using GIPHY's special sauce algorithm. This feature is best exhibited in GIPHY's Slack integration.
| Gif URL | Sticker URL |
|---|---|
| api.giphy.com/v1/gifs/translate | api.giphy.com/v1/stickers/translate |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| s: string(required) | "ryan gosling" or "ryan @gosling #cat" | Recommends a single gif. In order to pull such result supply query param "s" with desired term. It's possible to use @ or # to help search user channel(@) or gif's related to hashtag word |
| rating: string | g | Filters results by specified rating. Acceptable values include g, pg, pg-13, r. If you do not specify a rating, you will receive results from all possible ratings. |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
Successful Response (200 OK)
- data: GIF Object
- meta: Meta Object
Random Endpoint
GIPHY Random lets you add some weirdness to the conversation by returning a single random GIF or Sticker related to the word or phrase entered. If no tag is specified, the GIF or Sticker returned is completely random.
| Gif URL | Sticker URL |
|---|---|
| api.giphy.com/v1/gifs/random | api.giphy.com/v1/stickers/random |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| tag: string | "burrito" or "burrito @cat" | Filters results by specified tag. Retrieves any random gif. You can optimize results by supplying gif tag @username rating query parameters. |
| rating: string | g | Filters results by specified rating. If you do not specify a rating, you will receive results from all possible ratings. |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
Successful Response (200 OK)
- data: GIF Object
- meta: Meta Object
Action Register Endpoint
GIPHY’s Action Register registers each time a user views, clicks, or sends a GIF or Sticker and plays an important role in helping GIPHY improve your user’s search results.
INSTRUCTIONS
On almost all of our endpoints we return an Analytics Object for each of the GIF in the response for most endpoints.
To register an action when user views/clicks/sends a GIF, you should make a request by hitting the corresponding URL in the Analytics Object as such, and append the required params in the URL.
| Impression | Click | Send |
|---|---|---|
| GET analytics->onload->url | GET analytics->onclick->url | GET analytics->onsent->url |
BEST PRACTICE
We recommend getting a Random ID for each user by using the Random ID Endpoint. This will allow GIPHY’S API to adjust responses to your users without the use of personally identifiable information.
| Request Parameters: | Example: | Description: |
|---|---|---|
| random_id: string(required) | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
| ts: integer (int)(required) | 1527703430507 | A UNIX timestamp in milliseconds corresponding to when the action occurred. |
Successful Response (200 OK)
Random ID Endpoint
GIPHY Random ID Endpoint allows GIPHY to generate a unique ID you can assign to each new user in your app.
To get the most out of Random ID, we recommend sending the random_id param with all compatible endpoints. This lets us adjust the API response to your users’ preferences and improve their GIF experience while maintaining their privacy.
| URL |
|---|
| api.giphy.com/v1/randomid |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
Successful Response (200 OK)
- data: Random ID Object
- meta: Meta Object
The GIPHY Emoji Endpoints
GIPHY has released a feature across all GIPHY apps and platforms that makes GIPHY’s uniquely diverse emoji library more accessible than ever. Pairing custom artwork with a purpose-built API endpoint, GIPHY emojis allow you to bring animated reaction emojis to your users with style and ease.
The Emoji Endpoint
This endpoint is used to fetch GIF Objects for the set of GIPHY Emoji.
Variations
- The GIF Objects returned by this endpoint have the additional property
variation_count - If this value is populated with a number greater than 0, it indicates that the emoji has some number of variations. These variations represent different stylings or skin tones for that emoji.
| URL |
|---|
| api.giphy.com/v2/emoji |
| Request Parameters: | Example: | Description: |
|---|---|---|
| limit: integer (int32) | 20 | The maximum number of objects to return. (Default: 25) |
| offset: integer (int32) | 5 | Specifies the starting position of the results. (Default: 0) |
Successful Response (200 OK)
- data: Emoji Object[]
- pagination: Pagination Object
- meta: Meta Object
The Emoji Variations Endpoint
If an emoji's' variation_count is greater than 0, use the Emoji Variations Endpoint to fetch its variations.
Fetch the variations associated with a given emoji using the "id" property of the The GIF Object.
| URL |
|---|
| api.giphy.com/v2/emoji/{gif_id}/variations |
Successful Response (200 OK)
- data: Emoji Object[]
- meta: Meta Object
On the front-end, we reccomend displaying the variations in a tray above the emoji, as is a standard in popular platforms across mobile and web.
Check out the GIPHY Mobile Apps, or the GIPHY SDK, to see how we've chosen to display emoji variations.
Get GIF by ID Endpoint
Get GIF by ID returns a GIF’s metadata based on the GIF ID specified.
- Optionally, use the &rating param to tailor the response per your preferences. Read more here about content ratings.
| URL |
|---|
| api.giphy.com/v1/gifs/<gif_id> |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| gif_id: string(required) | xT4uQulxzV39haRFjG | The ID of the GIF you want details for. |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
| rating: string | g | If the GIF has a rating higher than the rating parameter, the API will return an empty response with a Meta Object containing a 4xx error code. |
Successful Response (200 OK)
- data: GIF Object
- meta: Meta Object
Error 4xx/5xx
- data: []
- meta: Meta Object
Get GIFs by ID Endpoint
Get GIFs by ID returns metadata of multiple GIFs based on the GIF IDs specified.
- Optionally, use the &rating param to tailor the response per your preferences. Read more here about content ratings.
| URL |
|---|
| api.giphy.com/v1/gifs |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| ids: string(required) | xT4uQulxzV39haRFjG, 3og0IPxMM0erATueVW | Filters results by specified GIF IDs, separated by commas. Maximum GIF IDs: “100” |
| random_id: string | e826c9fc5c929e0d6c6d423841a282aa | An ID/proxy for a specific user. |
| rating: string | g | Filters results by specified rating. Acceptable values include g, pg, pg-13, r. If you do not specify a rating, you will receive results from all possible ratings. |
Successful Response (200 OK)
- data: GIF Object[]
- pagination: Pagination Object
- meta: Meta Object
Upload Endpoint
GIPHY Upload allows you to upload your content programmatically on GIPHY.com. We accept animated GIFs or video files up to 100MB.
Note: If you're using a rate-limited key assigned by the developer portal, you will not be able to specify a GIPHY channel username to your request and you will be limited to 10 uploads per day. To have these limits removed, you can apply for a production key from your dashboard. Only approved apps will be able to include a GIPHY channel username. You can use this endpoint to upload your content, attach tags, and other meta tag in a single HTTP or HTTPS POST request.
| URL |
|---|
| upload.giphy.com/v1/gifs |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| username: string | JoeCool3000 | Your assigned username (required for approved apps only). |
| file: string(binary) | The animated GIF or video file you'd like to upload. (Local file resource, required if no source_image_url supplied). | |
| source_image_url: string | http://www.mysite.com/myfile.mp4 | The URL for the image or video you wish to upload (required if no file parameter specified). |
| tags: string | pets, cat, meow | A comma delimited list of tags to be applied to the upload. |
| source_post_url: string | http://www.mysite.com/my-post/ | The URL of the source of the asset. |
Successful Response (200 OK)
- meta: Meta Object
Categories API
Providers users a list of Gif categories on the GIPHY network.
| URL |
|---|
| api.giphy.com/v1/gifs/categories |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
Successful Response (200 OK)
- data: Category Object[]
- pagination: Pagination Object
- meta: Meta Object
Autocomplete API
Providers users a list of valid terms that completes the given tag on the GIPHY network.
| URL |
|---|
| api.giphy.com/v1/gifs/search/tags |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| q: string(required) | foo | Tag term. |
| limit: integer (int32) | 20 | The maximum number of objects to return. (Default: 5) |
| offset: integer (int32) | 5 | Specifies the starting position of the results. (Default: 0) |
Successful Response (200 OK)
- data: Term Object[]
- meta: Meta Object
Channel Search Endpoint
Channel Search endpoint returns all the GIPHY channels matching the query term
| URL |
|---|
| api.giphy.com/v1/channels/search |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| q: string(required) | foo | Accepts term to search through GIPHY’s channels |
| limit: integer (int32) | 20 | The maximum number of objects to return. Default: “25” Maximum: “50” |
| offset: integer (int32) | 5 | Specifies the starting position of the results. Default: “0” |
Successful Response (200 OK)
- data: Channel Object[]
- pagination: Pagination Object
- meta: Meta Object
Search Suggestions
Providers users a list of tag terms related to the given tag on the GIPHY network.
| URL |
|---|
| api.giphy.com/v1/tags/related/<term> |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
| term: string(required) | haha | Tag term. |
Successful Response (200 OK)
- data: Term Object[]
- meta: Meta Object
Trending Search Terms API
Provides users a list of the most popular trending search terms on the GIPHY network.
| URL |
|---|
| api.giphy.com/v1/trending/searches |
| Request Parameters: | Example: | Description: |
|---|---|---|
| api_key: string(required) | YOUR_API_KEY | GIPHY API Key. |
Successful Response (200 OK)
- data: String[]
- meta: Meta Object