Skip to main content

An API Wrapper for Sv443's JokeAPI

Project description

Sv443's Joke API Wrapper

Downloads CircleCI

An API wrapper for Sv443's joke api which provides simple yet versatile functionality, while also maintaining a readable codebase.


You can install jokeapi through pip by using pip install jokeapi

So far there are no build from source instructions.


The wrapper is structured in such a way that the end-user should only ever have to interact with one function. This function is get_joke()



  from jokeapi import Jokes # Import the Jokes class

  j = Jokes()  # Initialise the class
  j.get_joke()  # Retrieve a random joke



A list of categories that the returned joke should fit in. Options are: programming, miscellaneous, dark

If left blank it will default to use Any.

  joke = get_joke(categories=['programming', 'dark'])  # Will return a joke that fits in either the programming or dark category.


A list of properties that the joke shouldn't have. Options are: nsfw, religious, political, racist, sexist

If left blank it will default to None.

  joke = get_joke(blacklist=['nsfw', 'racist'])  # Will return a joke that does not have either the flag "nsfw" or "racist".


The format in which the API should respond. Options are: json, yaml, xml, txt

If left blank it will default to json.


  joke = get_joke(response_format="xml")  # Will return a joke in xml format.


The type of joke returned. Options are: single, twopart

If left blank it will default to Any


  joke = get_joke(type="twopart")  # Will return a twopart joke; both a setup and a delivery.


A string to search for in jokes.

If left blank it will default to None


  joke = get_joke(search_string="the")  # Will return a joke with the word "the" in it.
  # If there are no jokes then it will return the error from the API.


The range in which the selected joke should fall. ID's are decided by the order in which jokes are submitted. The argument passes should be in form of list or tuple, and should not exceed length of 2 items. First item should be minimum 0.

If left blank it will default to the maximum range.


  joke = get_joke(id_range=[10,100])  # Will return a joke with the ID between 10 and 100


Depending on what format is chosen different things will be returned.


A succesful API call will return:

      "category": "Miscellaneous",
      "type": "twopart",
      "setup": "I told my psychiatrist I got suicidal tendencies.",
      "delivery": "He said from now on I have to pay in advance.",
      "flags": {
          "nsfw": false,
          "religious": false,
          "political": false,
          "racist": false,
          "sexist": false
      "id": 94,
      "error": false


A succesful API call will return:

<?xml version='1.0'?>
    <joke>My ex had an accident. I told the paramedics the wrong blood type for her. She'll finally experience what rejection is really like.</joke>


A succesful API call will return:

category: "Programming"
type: "single"
joke: "Your momma is so fat, you need to switch to NTFS to store a picture of her."
  nsfw: false
  religious: false
  political: false
  racist: false
  sexist: false
id: 56
error: false


A succesful API call will return:

Why does no one like SQLrillex?

He keeps dropping the database.


The wrapper can raise multiple different errors depending on what you did wrong.

ValueErrors will always be raised with expected errors.

The errors are descriptive enough that you should be able to solve them with the information provided in the error message. If not, feel free to ask me through one of the channels provided below.

Developer contact: Discord Issue Tracker e-mail Twitter

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jokeapi, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size jokeapi-0.2.0.tar.gz (5.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page