Documentation

Here you have detailed documentation of all available API functions. To get started, you can make the sample request for each endpoint, download an SDK, or run in Postman (see bottom of left navigation).

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.

GET
https://api.humorapi.com/jokes/search
Example Request and Response
GET
https://api.humorapi.com/jokes/search?number=3&keywords=horse,man
{
    "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
}

Random Joke

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

GET
https://api.humorapi.com/jokes/random
Example Request and Response
GET
https://api.humorapi.com/jokes/random
{
    "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.

POST
https://api.humorapi.com/jokes/analyze
Example Request Body
POST
https://api.humorapi.com/jokes/analyze
What do you call a deer without eyes? No ideer.
Response
{
    "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.

POST
https://api.humorapi.com/jokes
Example Request Body
POST
https://api.humorapi.com/jokes
What do you call a deer without eyes? No ideer.
Response
{
    "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.

POST
https://api.humorapi.com/jokes/{id}/upvote
Example Request
POST
https://api.humorapi.com/jokes/123/upvote
Response
{
    "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.

POST
https://api.humorapi.com/jokes/{id}/downvote
Example Request
POST
https://api.humorapi.com/jokes/123/downvote
Response
{
    "message": "Thanks for submitting a downvote."
}

Search Memes

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.

GET
https://api.humorapi.com/memes/search
Example Request and Response
GET
https://api.humorapi.com/memes/search?number=3&keywords=rocket
{
    "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

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.

GET
https://api.humorapi.com/memes/random
Example Request and Response
GET
https://api.humorapi.com/memes/random?keywords=rocket
{
    "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.

POST
https://api.humorapi.com/memes/{id}/upvote
Example Request
POST
https://api.humorapi.com/memes/123/upvote
Response
{
    "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.

POST
https://api.humorapi.com/memes/{id}/downvote
Example Request
POST
https://api.humorapi.com/memes/123/downvote
Response
{
    "message": "Thanks for submitting a downvote."
}

Search Gifs

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.

GET
https://api.humorapi.com/gif/search
Example Request and Response
GET
https://api.humorapi.com/gif/search?query=dog&number=3
{
    "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

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.

GET
https://api.humorapi.com/praise
Example Request and Response
GET
https://api.humorapi.com/praise?name=Alex&reason=you+did+it+again
{
    "text": "Bravo Alex, you mastermind, you did it again."
}

Insult

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.

GET
https://api.humorapi.com/insult
Example Request and Response
GET
https://api.humorapi.com/insult?name=Alex&reason=you+dropped+the+ball
{
    "text": "Holy moley, you dropped the ball Alex, you dingbat."
}

Rate Word

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.

GET
https://api.humorapi.com/words/rate
Example Request and Response
GET
https://api.humorapi.com/words/rate?word=cookie
{
    "rating": 0.57
}

Generate Nonsense Word

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.

GET
https://api.humorapi.com/words/nonsense/random
Example Request and Response
GET
https://api.humorapi.com/words/nonsense/random
{
    "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

Each API plan comes with a daily quota of points. Every API call you make costs a certain amount of points. Usually, every request is
1 point
and
0.01 points
per result returned, but there are many exceptions. At the bottom of each endpoint description you will find information about the number of points required for that endpoint.

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 100,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.

Create Account

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.

Humor API Python Tutorial Humor API Python Tutorial

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

Humor API Python Tutorial

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

pip install setuptools
Humor API Python Tutorial

Then install the setup.py page

python setup.py install
Humor API Python Tutorial Humor API Python Tutorial

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

pip install openapi_client
Humor API Python Tutorial

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

pip install urllib3
Humor API Python Tutorial
pip install requests
Humor API Python Tutorial
pip install pandas --user
Humor API Python Tutorial

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
Humor API Python Tutorial

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.

Humor API Python Tutorial

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.

Humor API Python Tutorial

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.

Humor API Python Tutorial

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.