Packages

Here are the official packages for the API. If you cannot find your programming language here, you can make your own package.

Node.js

Installation

npm install animality

The Node.js package is available for use in Node Package Manager.

Examples

const Animality = require('animality');
// ES6: import Animality from 'animality';
Animality.getAsync('cat').then(console.log);

This outputs the following object in the terminal:

{
  "type": "cat",
  "animal": "cat",
  "image": "https://cdn.animality.xyz/cat/10.png",
  "fact": "Cats often communicate with their eyes.",
  "image_id": "25785c60-4b00-435e-83b0-13f9bb174f55",
  "fact_id": "21e7839d-ec66-49b1-8e87-cf1c4785e9b7"
}

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

const Animality = require('animality');
// ES6: import Animality from 'animality';

Animality.getAsync(['cat', 'dog', 'panda']).then(console.log);

This outputs the following array of objects in the terminal:

[
  {
    "type": "cat",
    "animal": "cat",
    "image": "https://cdn.animality.xyz/cat/5.png",
    "fact": "Cats are known for their curious nature.",
    "image_id": "4e112573-88ac-4824-b3ed-787769edb295",
    "fact_id": "66e79196-0bbb-491f-b08e-ca9364842671"
  },
  {
    "type": "dog",
    "animal": "dog",
    "image": "https://cdn.animality.xyz/dog/11.png",
    "fact": "Dogs are pack animals and thrive in a social environment.",
    "image_id": "20b70237-fdf0-44ff-a229-5bb7c60fb22c",
    "fact_id": "402c4d9d-dcad-496c-9c08-6593049353f0"
  },
  {
    "type": "panda",
    "animal": "panda",
    "image": "https://cdn.animality.xyz/panda/6.png",
    "fact": "Pandas are known to consume up to 12 kilograms of bamboo a day.",
    "image_id": "f04142cd-1d0e-437b-92d4-8bde1b37c140",
    "fact_id": "6a1966dc-888e-4c63-926e-28818b021890"
  }
]

This package also allows you tu generate random animals by using random as the animal type.

const Animality = require('animality');
// ES6: import Animality from 'animality';

Animality.getAsync('random').then(console.log);

Python

Installation

pip install animality-py

The Python package available for use in Python Package Index.

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:

  • libcurl (Linux only)
  • pthreads (Linux only, might be already installed by default)
  • wininet (Windows only, might be already installed by default)

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(())
}