Cataas API

Cat as a Service API wrapper for JavaScript and TypeScript.

Cat as a Service is a REST API to spread peace and love (or not) thanks to cats.

Features

• Simple API for fetching cat images and GIFs
• Download images directly
• Filter by tags, apply effects, and customize text
• TypeScript support
• Edge case and error handling

Install

npm install --save cataas-api

Tip: If you only need the URL encoder, see the url-encoder branch.

Usage Examples

Constructor

const Cataas = require("cataas-api");
const cataas = new Cataas();
const gif = {
  Gif: true,
  Size: "md",
  Text: "hey dude",
  Filter: "paint",
  TextSize: 35,
  TextColor: "LightBlue",
};
const resized = {
  Width: 300,
  Height: 200,
};
cataas.options = gif;
cataas.options = resized;

encode()

const encodedUrl = cataas.encode();

encodeById(id)

const encodedUrl = cataas.encodeById("[ID]");

async get()

cataas.encode();
cataas
  .get()
  .then((readable) => {
    const stream = new fs.createWriteStream("cat.png");
    readable.pipe(stream);
  })
  .catch((e) => console.error(e));

async download(path)

cataas.encode();
cataas
  .download("cat.png")
  .then((successful) => {
    if (successful) {
      console.log("Downloaded file successfully");
    }
  })
  .catch((e) => console.error(e));

async getAllTags()

cataas.encode();
cataas
  .getAllTags()
  .then((tags) => {
    console.log("Tags length:", tags.length);
  })
  .catch((e) => console.error(e));

async getCats(tags, options)

cataas.encode();
cataas
  .getCats(["cute"])
  .then((cats) => console.log("Results length:", cats.length))
  .catch((e) => console.error(e));

TypeScript Example

import Cataas from "cataas-api";

const cataas = new Cataas();
cataas.encode();
cataas
  .getCats(["cute"], { Limit: 5 })
  .then((cats) => {
    cats.forEach((cat) => {
      console.log(`${cat.id}: ${cat.tags}`);
    });
  })
  .catch((e) => console.error(e));

API Reference

Constructor

new Cataas(options?)

options (object):

• Gif: boolean
• Tag: string
• Text: string
• Width: number
• Height: number
• TextSize: number
• TextColor: string
• Size: "or" | "sq" | "md" | "sm"
• Filter: "pixel" | "paint" | "mono" | "blur" | "sepia" | "negative"

Methods

encode()

Returns the encoded URL based on current options.

encodeById(id)

Returns the encoded URL for a specific cat image ID.

get()

Returns a readable stream for the image or GIF.

download(path)

Downloads the image to the specified path.

getAllTags()

Returns an array of available tags.

getCats(tags, options?)

Returns an array of cat objects filtered by tags and options.

Tips

• After setting Gif: true in options, Tag is ignored
• Always call encode() or encodeById() before get() or download()

Reference

API website

License

MIT