Documentation

Search Jokes

With over 50,000 jokes, you should find something for any occasion. There are 27 categories to choose from but you can also search for very specific words within jokes.

{
    "jokes": [
        {
            "id": 35642,
            "joke": "A man walked into a cowboy bar and ordered a beer just as President Bush appeared on the television. After a few sips, he looked up at the television and mumbled, \"Now, there's the biggest horse's ass I've ever seen.\" A customer at the end of the bar quickly stood up, walked over to him, and decked him. A few minutes later, as the man was finishing his beer, Mrs. Bush appeared \n on the television. \"She's a horse's ass too,\" the man. This time, a customer at the other end of the bar quickly stood up, walked over \n to him, and knocked him off his stool. \"Damn it!\" the man said, climbing back up to the bar. \"This must be Bush country!\" \"Nope,\" the bartender replied. \"Horse country!\""
        },
        {
            "id": 39052,
            "joke": "The General went out to find that none of his G.I.s were there. One finally ran up, panting heavily.\"Sorry, sir! I can explain, you see I had a date and it ran a little late. I ran to the bus but missed it, I hailed a cab but it broke down, found a farm, bought a horse but it dropped dead, ran 10 miles, and now I`m here.\"The General was very skeptical about this explanation but at least he was here so he let the G.I. go. Moments later, eight more G.I.s came up to the general panting, he asked them why they were late.\"Sorry, sir! I had a date and it ran a little late, I ran to the bus but missed it, I hailed a cab but it broke down, found a farm, bought a horse but it dropped dead, ran 10 miles, and now I`m here.\"The General eyed them, feeling very skeptical but since he let the first guy go, he let them go, too. A ninth G.I. jogged up to the General, panting heavily.\"Sorry, sir! I had a date and it ran a little late, I ran to the bus but missed it, I hailed a cab but...\"\"Let me guess,\" the General interrupted, \"it broke down.\"\"No,\" said the G.I., \"there were so many dead horses in the road, it took forever to get around them.\""
        },
        {
            "id": 41701,
            "joke": "A man has a racehorse, never won a race. Man in disgust says, Horse, you win today or you pull a milk wagon tomorrow morning.\" The starting gate opens, the horses take-off, they move the gate away and there lays his horse asleep on the track. He kicks the horse and asks, \"WHY ARE YOU SLEEPING. The horse, half asleep says, \"I have to get up at three in the morning.\""
        }
    ],
    "available": 541
}

Create Joke

Use a large language model to create a joke for a certain topic or even multiple topics.

{
        "joke": "What's a pirate's least favorite exercise? The plank."
}

Random Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

{
    "id": 38242,
    "joke": "Q: How many divorced men does it take to screw in a light bulb?\nA: None, the sockets go with the house."
}

Analyze Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

What do you call a deer without eyes? No ideer.

{
    "joke": "What do you call a deer without eyes? No ideer.",
    "tags": [
        "ANIMAL"
    ]
}

Submit Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

What do you call a deer without eyes? No ideer.

{
    "joke": {
        "id": 52625,
        "joke": "What do you call a deer without eyes? No ideer.",
        "tags": [
            "ANIMAL"
        ]
    },
    "message": "Thanks for submitting the joke. We will evaluate the joke asap."
}

Upvote Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

{
    "message": "Thanks for submitting an upvote."
}

Downvote Joke

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

{
    "message": "Thanks for submitting a downvote."
}

Search Memes

With over 200,000 memes, you'll surely find something funny. You can even search for text within memes and filter by user ratings.

{
    "memes": [
        {
            "id": 6696,
            "url": "https://i.imgur.com/1rmAxUG.jpg",
            "type": "image/jpeg"
        },
        {
            "id": 6697,
            "url": "https://i.imgur.com/ELT8zMQ.jpg",
            "type": "image/jpeg"
        },
        {
            "id": 6698,
            "url": "https://i.imgur.com/8JTc5z3.jpg",
            "type": "image/jpeg"
        }
    ],
    "available": 32
}

Random Meme

Get a random meme out of over 200,000 memes and growing.

{
    "id": 50561,
    "url": "https://preview.redd.it/hg0zn2mhjsh01.png?width=640&crop=smart&auto=webp&s=f19b0a87edfc6c71b35ec9aceb64799cd532ff59",
    "type": "image/png"
}

Upvote Meme

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

{
    "message": "Thanks for submitting an upvote."
}

Downvote Meme

This endpoint is similar to the Search Jokes endpoint but you'll receive a random joke every time.

{
    "message": "Thanks for submitting a downvote."
}

Search Gifs

Search through hundreds of thousands of gifs to match any reaction you want.

{
    "images": [
        {
            "url": "https://media.tenor.com/images/f97a4505bb4f972cef00bc377aff7f4e/tenor.gif",
            "width": 498,
            "height": 364
        },
        {
            "url": "https://media.tenor.com/images/1d73fd5b39730fd356b482128eb3746a/tenor.gif",
            "width": 498,
            "height": 490
        },
        {
            "url": "https://media.tenor.com/images/6e45dbbc34d8427ffcc322024c73f8fc/tenor.gif",
            "width": 498,
            "height": 498
        }
    ]
}

Praise

Praise somebody for something.

{
    "text": "Bravo Alex, you mastermind, you did it again."
}

Insult

Insult somebody for something.

{
    "text": "Holy moley, you dropped the ball Alex, you dingbat."
}

Rate Word

Rate a word on its funniness.

{
    "rating": 0.57
}

Generate Nonsense Word

Generate a funny sounding nonsense word.

{
    "word": "caboo",
    "rating": 0.41
}

• Clean
• Animal
• Food
• Sexual
• Knock Knock
• Sport
• Blondes
• Law
• Nerdy
• Relationship
• Deep Thougths
• Dark
• One Liner
• Political
• Chuck Norris
• Yo Momma
• NSFW
• Religious
• School
• Jewish
• Racist
• Insults
• Sexist
• Holiday
• Analogy
• Christmas
• Kids

Rate Limiting & Quotas

When you are on the free plan and your daily quota is used up, the API will respond with the error code 402 and no more calls can be made until your quota resets.

You have complete control over your quota by looking at your console dashboard and checking the API response headers that appear with every answer from the API. These response headers are:

• X-API-Quota-Request: The number of points used by the request.
• X-API-Quota-Used: The number of points used in total today. This number resets to zero at midnight UTC (click here to compare to your local time zone).
• X-API-Quota-Left: The number of points left today (depends on your plan).

Rate Limiting

There is a limit of how many requests you can make per second. The limits depend on the plan you are on. If you try making more requests you will receive a 429 error.

• Free: 60 requests in 1 minute
• Jack: 2 requests per second
• Jester: 5 requests per second
• Joker: 10 requests per second

Authentication

To use the API you need an API key. You can get a free one by simply signing up here.

Once you have your API key, you have to put it in the request URL for every request you make like so ?api-key=YOUR-API-KEY.

Attention: Only the first query parameter is prefixed with a ? (question mark), all subsequent ones will be prefixed with a & (ampersand). That is how URLs work and nothing related to our API. Here's a full example with two parameters api-key and include-tags: https://api.humorapi.com/jokes/search?api-key=YOUR-API-KEY&include-tags=tag1,tag2.

Alternatively, you can put the API key in the request header as x-api-key.

Tutorial

Humor API is a jokes API application where you can access over 50,000 jokes in 27 categories. It also has a meme API feature where you can access over 200,000 memes. In this tutorial, we will look at getting jokes from specific tags.

The first thing to do is to create an account with Humor API. This is important because it is the only way to get an authentication key. You can find your key on your profile page. Next, we need to install the package.

Installation

On the SDK page, select an SDK library in the language of your choice. We will use Python for this tutorial. Open an editor and inspect the content of the library. README.md contains instructions on how to install the package using either git or setuptools.

The setup.py page contains the information and metadata needed for building, distributing and installing the open_client package which we will be using.

To install open_client using setup.py install, we need to install all relevant packages with pip, starting with python setuptools.

pip install setuptools

Then install the setup.py page

python setup.py install

It loads all the dependencies for openapi-client and makes the package available for installation.

pip install openapi_client

We will be needing other libraries like urllib3, requests, and pandas. Install those too with pip.

pip install urllib3

pip install requests

pip install pandas --user

Interacting with the Jokes API

In the body of the editor, we will write the main code that allows us to interact and have access to the Jokes API. On the documentation page, there is detailed information on available API functions, endpoints, and response headers of each endpoint. We will use the 'search jokes' endpoint and include the needed tags.

First, we import the installed packages.

import openapi_client
import urllib3
import requests
import json
import pandas as pd

At this stage, we'll need the authentication key. The authentication key is added to the url of the api.

#defining our variables
url = 'https://api.humorapi.com/jokes/search?api-key=972aca79287xxxxxxxxxxxxxxxxxxx&include-tags=dark,relationship'
headers = {'content-type': 'application/json'}

The variable, url is the link to api.humor.com and it contains different parameters like the api key, keywords, tags, min-rating, max-length etc. In this case, we will use search_jokes endpoint, the api key and the tags of jokes we want, which are 'dark, law and relationship'.

Connection to the API will be made using urllib3 and request. The pool manager instance will handle the thread safety.

http = urllib3.PoolManager()

Then we make a request using request(). request() will return a HTTPResponse object.

http = urllib3.PoolManager()
req = http.request('GET', url, headers= headers)

print(type(req))

#<class 'urllib3.response.HTTPResponse'>

The request is made. We will view the output with a .data method.

print(req.data)
# req.data prints the jokes in text format

The output is in a text-like format, and its class is 'bytes'. It needs to be in JSON format so we can manipulate it using dictionary methods.

joke = json.loads(req.data.decode('UTF-8'))
print(joke)

print(type(joke))  #<class 'dict'>

We can check out the keys of the dictionary

print(joke.keys())

#dict_keys(['joke', 'available'])

On further examination, when we inspect the output for print(joke), joke key object is a list that contains two items - an id and joke as values.

We can represent this in a tabular form using pandas, with id and joke as column title.

We save a copy of the joke key to a new list

newj = joke['jokes']

And import it into a pandas dataframe

df = pd.DataFrame(newj)
print(df)

We get this output.

We can increase the number of jokes to get a more tabular feel. In the url, add a parameter, number, and set the value to 6.

url = 'https://api.humorapi.com/jokes/search?api-key=972aca7928764655af7xxxxxxxxxxx&number=6&include-tags=dark,law,relationship'

Run the program again.

Accessing Humor API's jokes through the jokes api is quite a straightforward process and this tutorial shows how to do it from start to finish. The entire process can be run on any editor and console or notebook environment.