The Cat API

Any dramas or questions, feel free to give me a shout @AdenForshaw


Why get an API Key?

You can make as many requests as you like to api/images/get without an API key, but you'll only get access to the first 1000 Images. With an API Key you get access to all the Images, and you can Vote, Favourite and even Upload your own pictures.

Have one instantly emailed to you now.


What is a sub_id?


This lets you pass a unique identifier, like a Facebook or Twitter User id, with your API requests. This way you can get all the Favourites and Votes set by one of your Users. We don't care what it is and will not use this information for anything else.


/api/images/get
This'll get you all the fancy cat Images you can handle

Important: To protect yourself from Copyright issues, when you show an Image you MUST have it linked to; or clearly show the 'source_url' the value of the XML, or leave the link in-place with HTML format. This then links back to the image on thecatapi.com, where we then link to where we do the same to the last known Copyright holder.

Parameters

Name Values Required Description Default
api_key apply for one No Passing this gives you access to all the images, voting, favouriting, uploading etc none
image_id string No Unique id of the Image to return. Will only ever return one Image. none
format xml / html / src No The output format, as XML, an HTML img tag, or the src to use in an img tag. src
results_per_page Between 1 and 100 No The number of Cats to respond with. If format is set to src then only one will be returned. 1
type jpg / png / gif No A comma separated string of file types to return. e.g. jpg,png jpg,gif,png
category complete list No Filter the Cats returned to those wearing hats, in space, in boxes etc. none
size small, med, full No Size of returned Images, small = 250x, med = 500x, full = original size. full
sub_id string No Passing this will return the value of any Favourite or Votes set with the same sub_id for the image. none

Example: This'll return you xml data for 20 random cats.

http://thecatapi.com/api/images/get?format=xml&results_per_page=20

/api/images/vote
This lets you or one of your users score an image 1-10

Parameters

Name Values Required Description Default
api_key Yes none
image_id string Yes Unique id of the image to vote on. none
score integer Yes The score you want to give to the image 1 = bad / 10 = good. none
sub_id string No Any value you wish to associate with this vote, could be a unique id you have for one of your Users like a facebook id. This allows you to only have one vote on an Image per User. none

Example: This is an example of User 12345 giving Image bC24 a score of 10

http://thecatapi.com/api/images/vote?api_key=[YOUR-API-KEY]&sub_id=12345&image_id=bC24&score=10

/api/images/getvotes
This gets all the votes cast with your api_key

Parameters

Name Values Required Description Default
api_key Yes none
sub_id string No If this is passed, then only votes cast with this sub_id will be returned. Useful to find out which votes have been cast by which of your Users. none

Example: This is an example will return all the votes cast by user 12345

http://thecatapi.com/api/images/getvotes?api_key=[YOUR-API-KEY]&sub_id=12345

/api/images/favourite
This lets you or one of your Users favourite an Image

Parameters

Name Values Required Description Default
api_key Yes none
image_id string Yes Unique id of the image to favourite or un-favourite none
action string (add or remove) No This allows you to say whether to add a favourite or remove it add
sub_id string No Any value you wish to associate with this, could be a unique id you have for one of your Users like a facebook id. This allows you to favourite this Image once per User. none

Example: This is an example of User 12345 favouriting Image bC24

http://thecatapi.com/api/images/favourite?api_key=[YOUR-API-KEY]&sub_id=12345&image_id=bC24

Example: This is an example of User 12345 un-favouriting Image bC24

http://thecatapi.com/api/images/favourite?api_key=[YOUR-API-KEY]&sub_id=12345&image_id=bC24&action=remove

/api/images/getfavourites
This gets all the favourites set with your api_key

Parameters

Name Values Required Description Default
api_key Yes none
sub_id string No If this is passed, then only the Favourites cast with this sub_id will be returned. Great for finding out which Images have been Favourited by a User. none

Example: This is an example will return all the Favourites for User 12345

http://thecatapi.com/api/images/getfavourites?api_key=[YOUR-API-KEY]&sub_id=12345

/api/images/report
This allows you to report an Image so it will not show up again when you make a get request with your api_key.

Parameters

Name Values Required Description Default
api_key Yes none
image_id string Yes Unique id of the image to report none
sub_id string No Any value you wish to associate with this, could be a unique id you have for one of your Users like a facebook id. This allows you to favourite this Image once per User. none
reason string No Any particular reason why it needs reporting, contains nothing but hippos, doesn't work etc none

Example: This will report Image 8 so it won't show up again for requests with your api_key.

http://thecatapi.com/api/images/report?api_key=[YOUR-API-KEY]&sub_id=12345&image_id=8

/api/categories/list
Returns a list of all the active categories.

Example:

http://thecatapi.com/api/categories/list

/api/stats/getoverview
This returns the total get requests/ votes/ favourites/ and images served for your account.

Parameters

Name Required Default
api_key Yes none

Example: This will return the overview of the stats for your account.

http://thecatapi.com/api/stats/getoverview?api_key=[YOUR-API-KEY]



Post any feedback or comments below


comments powered by Disqus