Web Shepherd API docs

Overview

This section contains an overview of the data provided and the API's purpose.

USING THE API

This is a public API that provides a list of endangered species and their characteristics in JSON format.
It supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

The API is organized into three sections:

  • Getting started introduces you to the operations offered by the API.
  • Implementation provides you with some code to get started.
  • Output provides an example of a successful response.

Getting Started

BASE URL

  • http://www.bloowatch.org

ENDPOINTS

Endpoint

What it does?

/developers/json/species

Returns an array of all species and their properties

/developers/json/species/{name}

Returns the selected species and its properties

PARAMETERS

{name} can be replaced with the following options:
  • bengal-tiger
  • giant-panda
  • blue-whale
  • asian-elephant
  • gorilla
  • snow-leopard
  • orangutan
  • sea-turtle
  • black-rhino
  • african-penguin
  • red-panda
  • polar-bear

Impementation

You can use this API by using fetch, jQuery or Axios.

Simple code example using fetch:

  async function getData() {
      try {
          const res = await fetch('http://bloowatch.org/developers/json/species');
          const data = await res.json();
          console.log(data);
      } catch(err) {
          console.log(err);
      }
  }
  getData();
              
  fetch('http://bloowatch.org/developers/json/species')
      .then(res => res.json())
      .then(jsonRes => console.log(jsonRes))
      .catch(error => console.log(error));
              

Output

An example of successful response for the url

http://bloowatch.org/developers/json/species/giant-panda:

  {success: "true", message: "list of species retrieved successfully", species: Array(1)}
  	message: "list of species retrieved successfully"
  		species: Array(1)
  		0:
  			description: "Giant panda bear is native to south central China and lives mainly high in the mountains in cool and wet bamboo forests which is their primary source of food. Pandas are skilled tree-climbers and good swimmers. They have been driven out of the lowland areas where they once lived because of farming and deforestation making it a vulnerable species. Improved conservation efforts and better survey methods have managed to increase the wild panda population."
  			habitat: "Bamboo forests on humid mountains"
  			image:
  				licence: ""
  				url: "/images/giant-panda_image.png"
  				__proto__: Object
  			location: "China"
  			name: "Giant Panda"
  			population: "2,000"
  			scientific_name: "Ailuropoda melanoleuca"
  			status: "Vulnerable"
  			status_legend: Array(3)
  				0: {_id: "5c597571c0335400178b32c9", status: "Critically endangered", abbreviation: "CR", description: "Faces an extremely high risk of extinction in the immediate future."}
  				1: {_id: "5c597571c0335400178b32c8", status: "Endangered", abbreviation: "EN", description: "Faces a high risk of extinction in the near future."}
  				2: {_id: "5c597571c0335400178b32c7", status: "Vulnerable", abbreviation: "VU", description: "Faces a high risk of endangerment in the medium term."}
  				length: 3
  				__proto__: Array(0)
  			url: "giant-panda"
  			__v: 0
  			_id: "5c597571c0335400178b32c6"
  			__proto__: Object
  		length: 1
  	__proto__: Array(0)
  success: "true"
  __proto__: Object