animality-docs

The official API Documentation for animality

💖 We are currently working on a new improved documentation and API

Usage

These are the 18 animal strings that can be used to send a request to the API:

NOTE: API Keys are not required to use the API.

Random Image

https://api.animality.xyz/img/<animal>

This endpoint allows you to request a random image URL for a specific animal. The data returned is a JSON object with a URL to the specified image.

{
  "link": "https://api.animality.xyz/images/dog/15.png"
}

Random Fact

https://api.animality.xyz/fact/<animal>

This endpoint allows you to request a random fact for a specific animal. The data returned is a JSON object with the fact as a string.

{
  "fact": "Dogs are as smart as a two-year-old baby."
}

Official Wrappers

Here are some official wrappers for this API. If you can’t find your programming language here, you can make your own.

Node.js

Installation

$ npm install animality

The Node.js wrapper for this API is available for use in Node Package Manager. It’s use is pretty straight-forward.

Example

const {Animality} = require('animality');
const animal = 'cat';
Animality.getAsync(animal, 'API_KEY').then(console.log);

This outputs the following object in the terminal:

{
  "name": "cat",
  "image": "An image URL here",
  "fact": "A fact here"
}

Other than that, this package also allows you to request multiple animals at the same time.

const {Animality} = require('animality');
const animals = ['cat', 'dog', 'panda'];
Animality.getAsync(animals, 'API_KEY').then(console.log);

This outputs the following array of objects in the terminal:

[
  {
    "name": "cat",
    "image": "An image URL here",
    "fact": "A fact here"
  },
  {
    "name": "dog",
    "image": "An image URL here",
    "fact": "A fact here"
  },
  {
    "name": "panda",
    "image": "An image URL here",
    "fact": "A fact here"
  }
]

Python

Installation

$ pip install animality-py

This API has a wrapper for it in Python. You can install it through the Python Package Index. Using it is quite simple.

Example

import animality
from asyncio import get_event_loop

async def run():
    animal = await animality.get("dog")
    print(animal.name, animal.image, animal.fact)
    random = await animality.random()
    print(random.name, random.image, random.fact)

get_event_loop().run_until_complete(run())

This outputs the following text in the terminal:

<Animal name="dog" image="..." fact="...">
<Animal name="..." image="..." fact="...">

C/C++

Required dependencies:

Installation

Windows (MinGW) or Linux

$ git clone https://github.com/animality-xyz/animality.h.git && cd animality.h/
$ gcc -c animality.c -o animality.o
$ ar rcs -o libanimal.a animality.o

Windows (Visual C++)

$ git clone https://github.com/animality-xyz/animality.h.git && cd animality.h
$ cl /LD animality.c

Example

The response from requesting to the library is this struct.

typedef struct {
    an_type_t type;    // animal name, as enum
    char * name;       // animal name, as string
    char * image_url;  // animal image URL
    char * fact;       // animal fact
} animal_t;

Here is a simple request example to the API. Please note that the following example is synchronous (aka blocking).

#include "animality.h"

int main() {
    // create our animal struct
    animal_t animal = AN_EMPTY_ANIMAL;

    // request for an animal
    an_get(AN_DOG, &animal);

    // do stuff with struct
    printf("animal image url: %s\n", animal.image_url);
    printf("animal fact: %s\n", animal.fact);
    
    // free animal struct once used
    an_cleanup(&animal);

    // global cleanup
    an_cleanup(NULL);

    return 0;
}

If you want an asynchronous request, try this example:

#include "animality.h"

// our request callback function!
void callback(const animal_t * animal) {
    printf("animal image url: %s\n", animal->image_url);
}

int main() {
    // create separate thread for requesting to the API
    const an_thread_t thr = an_get_async(AN_DOG, &callback);

    // this will run while the thread is still requesting to the API
    printf("Hello, World!\n");

    // wait for thread to terminate before we exit the main function
    an_thread_wait(thr);
    
    // global cleanup
    an_cleanup(NULL);
    
    return 0;
}

Rust

Installation

Add this to your Cargo.toml’s dependencies:

animality = "1.0.0"

Blocking Request

extern crate animality;
use animality::{Animality, Animal};

fn main() {
  let client = Animality::new("API_KEY");
  
  // request with the `Animal` enum
  let dog_image = client.image(Animal::Dog).unwrap();
  let dog_fact = client.fact(Animal::Dog).unwrap();
  
  // request from a string (case-insensitive) 
  let cat: Animal = "cat".parse().unwrap();
  let cat_image = client.image(cat).unwrap();
  let cat_fact = client.fact(cat).unwrap();
}

Async Request

extern crate animality;
extern crate tokio;

use animality::{Animality, Animal, RequestError};

#[tokio::main]
async fn main() -> Result<(), RequestError> {
  let client = Animality::new("API_KEY");
  
  // request with the `Animal` enum
  let dog_image = client.image_async(Animal::Dog).await?;
  let dog_fact = client.fact_async(Animal::Dog).await?;
  
  // request from a string (case-insensitive) 
  let cat: Animal = "cat".parse().unwrap();
  let cat_image = client.image_async(cat).await?;
  let cat_fact = client.fact_async(cat).await?;

  Ok(())
}