API Reference

Version Info

catapi.__version__

returns the version info in the form of Major.Minor.Patch

CatApi

class catapi.CatApi

Handles all requesting and returning of data from the cat api. You can get an api key at https://thecatapi.com/signup .

Signing up for the api is free and only takes a few seconds.

api_key

authentication key for thecatapi.com

Type:int

api_delete_session(url, params=None)

Starts an aiohttp session to send a delete request

api_get_session(url, params=None)

Starts an aiohttp client session and returns the result of fetching data.

If api_key is not set, this will raise an error.

api_post_session(url, data, params=None, json=False)

Uploads data to the url via post.

Parameters:

• url (string) – Url to post data to
• data (dict) – Dictionary of key/value pairs to post
• params (dict) – Key/Value pairs of parameters for url arguments
• json (boolean) – Whether or not to post the data as json

classmethod delete(session, url, headers, params)

Sends an http delete request to the url

delete_favorite(favorite_id)

Removes an item from your favorites

Also mapped to CatApi.delete_favourite()

Parameters:favorite_id (string) – ID of the image to delete a favorite from

delete_favourite(favourite_id)

Removes an item from your favourites

Also mapped to CatApi.delete_favorite()

Parameters:favourite_id (string) – ID of the image to delete a favourite from

delete_image(image_id)

Deletes an image specified by the image_id

Parameters:image_id (string) – ID of the image to delete

delete_vote(vote_id)

Deletes a particular vote.

Parameters:vote_id (string) – The string id of the vote to delete

favorite(image_id, sub_id)

Favorite an image.

Also mapped to CatApi.favourite()

Parameters:

• image_id (string) – ID of the image to favorite
• sub_id (string) –

  Custom content to add when favoriting the image

  Note: testing shows sub_id is required although thecatapi says not

favourite(image_id, sub_id)

Favourite an image.

Also mapped to CatApi.favorite()

Parameters:

• image_id (string) – ID of the image to favorite
• sub_id (string) –

  Custom content to add when favouriting the image

  Note: testing shows sub_id is required although thecatapi says not

get_analysis(image_id)

Get the analysis results of an image.

image_id: string

get_breeds(page=0, limit=5, attach_breed='')

Requests breeds from thecatapi. Without any parameters passed in, requests the first 5 breeds from the API.

Parameters:

• attach_breed (int (1 or 0)) – The usage of this is undocumented in the api documentation.
• page (int) – Which page to return results from
• limit (int) – How many results will make up a page.

get_categories(limit=7, page=0)

Gets the categories available through the api. By default, returns the current total of 7 categories.

Parameters:

• page (int) – Which page to return results from
• limit (int) – How many results will make up a page.

get_favorite(favorite_id)

Get a favorite specified by favorite id

Also mapped to CatApi.get_favourite()

Parameters:favorite_id (string) –

get_favorites(limit=100, page=0, sub_id='')

Gets all of your favorites.

Also mapped to CatApi.favourites()

Parameters:

• limit (int) – Amount of items per page
• page (int) – Which page to access
• sub_id (string) – Custom content placed when favoriting the image

get_favourite(favourite_id)

Get a favourite specified by favourite id

Also mapped to CatApi.get_favorite()

Parameters:favourite_id (string) –

get_favourites(limit=100, page=0, sub_id=None)

Gets all of your favourites.

Also mapped to CatApi.favorites()

Parameters:

• limit (int) – Amount of items per page
• page (int) – Which page to access
• sub_id (string) – Custom content placed when favouriting the image

get_image(image_id)

Gets a specific image by id from the api.

Parameters:image_id (string) – ID of the image to get

get_uploads(**kwargs)

Allows you to get images you have uploaded to thecatapi. Can accept up to 10 keyword arguments.

Parameters:

• breed_ids ([int]) – List of unique breed_id strings
• category_ids ([string]) – List of unique category_id strings
• format (string) – May be “json” or “src”
• include_favorite (int) – May be 0 or 1
• include_vote (int) – May be 0 or 1
• limit (int) – May be between 1 and 100, inclusive
• order (string) – May be “ASC”, “DESC”, or “RANDOM”
• original_filename (class:string) – get uploads that originally had this name. Length must be between 0 and 100 characters, inclusive.
• page (class:int) – Which page to get results from. Minimum value of 1
• sub_id (string) –
  • min length: 0
  • max length: 255

get_vote(vote_id)

Gets a particular vote.

Parameters:vote_id (string) – The string id of the vote to get

get_votes(limit=100, page=0, sub_id='')

Gets a list of all votes you have created. By default, with no options, this gets the first 100 votes on images you have cast.

Parameters:

• limit (int) – How many votes to have per page
• page (int) – The page number to get the votes from. Minimum 0
• sub_id (string) – Custom string stored with votes

search_breeds(breed=None)

Requests breeds from the cat API. If breed is None, it requests all breeds by default.

Parameters:breed (string) – A string with part or all of the cat breed name.

search_images(**kwargs)

search_images may take up to 8 args. By default, this returns a single random cat image.

Parameters:

• breed_id (string) – Breed id to narrow down the search with. Find breeds with CatApi.get_breeds()
• category_ids ([string]) – Filter based on category id. Currently does not appear to work.
• format (string) – May be “json” or “src”
• limit (int) – May be in the range of 1-100, inclusive
• mime_types ([string]) – A list of strings. Values this takes are currently unknown
• order (string) – May be “ASC”, “DESC”, or “RANDOM”
• size (string) – May be “full”, “med”, “small”, or “thumbnail”
• page (class`int`) – Which page to pull images from. Minimum value of 0

upload(filepath, sub_id='')

Uploads a file to thecatapi.com

Parameters:

• filepath (string) – Path to the jpg, png, gif, etc to upload
• sub_id (string) – Custom value you may add to be stored with the file

vote(image_id, value, sub_id)

Casts a vote on the image specified by image_id

Parameters:

• image_id (string) – String ID of the image to vote on
• value (int) – Upvote (1) or downvote (0)
• sub_id (string) – Custom message to store along with the vote

Abstract Classes

class catapi.models.abc.model_abc.Model

Abstract class for all database models.

All Models extend this abstract base class

to_dict()

Async method that returns all items in __slots__ formatted as a dict

Models

class catapi.models.analysis.Analysis

Analysis schema according to thecatapi.com

approved

Whether or not the image was approved. 1 == True, 0 == False

Type:int

created_at

Datatime string indicating when the analysis was performed

Type:string

image_id

String id of the image this analysis is from

Type:string

labels

Dicts containing information about analysis labels

Type:[dict]

moderation_labels

Dicts containing reasons the image may be under moderation

Type:[dict]

rejected

Whether or not the image was rejected. 1 == True, 0 == false

Type:int

vendor

The vendor performing the analysis

Type:string

class catapi.models.breed.Breed

Represents a breed model from thecatapi.com

TheCatApi schema for a breed is:

alt_names: string

Alternate names for the breed

country_code: string

Country code indicating where the breed originates

id: string

ID for this breed

life_span: string

Lifespan of the breed

name: string

Name of this breed

origin: string

Where the breed originates

temperment: string

General temperment of the breed

weight_imperial: string

General weight of the breed in pounds/ounces

weight_metric: string

General weight of the breed in kilograms/grams

wikipedia_url: string

Link to a wikipedia article about the breed

adaptability: int

min 1, max 5

affection_level: int

min 1, max 5

child_friendly: int

min 1, max 5

dog_friendly: int

min 1, max 5

energy_level: int

min 1, max 5

experimental: int

min 0, max 1

grooming: int

min 1, max 5

hairless: int

min 0, max 1

health_issues: int

min 1, max 5

hypoallergenic: int

min 0, max 1

intelligence: int

min 1, max 5

natural: int

min 0, max 1

shedding_level: int

min 1, max 5

rare: int

min 0, max 1

rex: int

min 0, max 1

short_legs: int

min 0, max 1

social_needs: int

min 1, max 5

stranger_friendly: int

min 1, max 5

suppress_tail: int

min 0, max 1

vocalisation: int

min 1, max 5

classmethod from_dict(breed_json)

Returns a Breed object created with the breed_json data.

breed_json: dict

class catapi.models.favorite.Favorite

TheCatApi schema for favorites

created_at: string

Datetime indicating when this favorite was created

id: string

String id of this favorite

image_id: string

String id of the image this favorite is for

sub_id: string

Custom information stored alongside the favorite

class catapi.models.image.Image

Image schema from thecatapi.

Note: This includes some which appear to be undocumented. It’s currently unknown if these undocumeted items are newly added in, or if they were simply overlooked.

id: string

string ID of the image

url: string

String url link to the image

sub_id: string

Custom string stored with the image

created_at: string

String datetime indicating when the image was created

original_filename: string

String containing the original filename

width: int

int indicating the width pixel measurement

height: int

int indicating the height pixel measurement

breed: Breed

A breed object containing any breed information stored with the image

categories: [Category]

A list of any categories the image belongs in

class catapi.models.vote.Vote

Vote schema according to thecatapi.

created_at: string

A string indicating when the vote was created

country_code: string

A string indicating the country of origin for the vote

value: Required int

An int indicating an upvote (1) or downvote (0)

image_id: string (required)

String ID referencing the image the vote applies to

sub_id: Required string

Custom information to store with the vote

id: string

String id of the vote