Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/growingdatafoundation/ipn-api

Indigenous Place Names API
https://github.com/growingdatafoundation/ipn-api

Last synced: about 1 month ago
JSON representation

Indigenous Place Names API

Host: GitHub
URL: https://github.com/growingdatafoundation/ipn-api
Owner: growingdatafoundation
Created: 2016-07-29T07:58:04.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2016-07-29T08:03:19.000Z (over 8 years ago)
Last Synced: 2024-08-02T12:43:45.851Z (4 months ago)
Language: PHP
Size: 4.74 MB
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: readme.md

Awesome Lists containing this project

awesome-starred - growingdatafoundation/ipn-api - Indigenous Place Names API (others)

README

* Base API: http://api.ala.org.au/
* old repository: https://github.com/NatureNinjas/whatgrowshere

# Install
=========

* Install dependencies

```
composer install
```

* Rename `example.ApiConfig.php` to `ApiConfig.php` and fill in your Api Keys.

Recomended: The `ApiConfig.php` should be moved out of the `htdocs`. Update the `require_once` directive for this file the index.php accordingly.

* if you want to use the Mongo cache you currently need to install MongoDB on your server and install the PHP Mongo drivers

# ALA Occurences aggregator API

## ala.occurences

* returns lists of occurrence counts of queried specimen for a given location

### GET:

```
/ala.occurences.php?include=ala.species&bname=Acacia&lat=-34.928726&lon=138.59994&radius=5
```

Params:

* `include` (optional): modules to include (see below)
* `bname`: binomial name search (starts with), currently interpreted as [genus](https://en.wikipedia.org/wiki/Genus)
* `lat`: latitude
* `lon`: longitude
* `rad`: radius
* `dump` (optional, debug!): pretty-dumps json for debugging

### POST

Submit a wkt plygon string

```
/ala.occurences.php?include=ala.species&bname=Acacia
/ala.occurences.php
```

Params:

* `include` (optional): modules to include (see below)
* `bname`: binomial name search (starts with), currently interpreted as [genus](https://en.wikipedia.org/wiki/Genus)
* `wkt`: (POST field only) wkt string
* `dump` (optional, debug!): pretty-dumps json for debugging

### Include modules

available modules:

* `ala.species`: fetches details for each returned species of occurence search
* `ala.explore.groups`: counts number of secies by group for a location/region

Modules can be set with the `include` parameter. Multiple modules as comm-separated list, e.g. `include=ala.species,ala.explore.groups`

Note, `ala.explore.groups` works only in GET mode. ALA doesn't suppot polygons for group counts. The api doens't break when included into POST, but will log a `_status` 400'.

`"ala":{ ... "explore":{"groups":{"_status":400,"_errors":["No polygon requests supported"],"count":false,"groups":[]}}}}`

### Response

Example response with `include=ala.species`

```javascript
{
"ala": {
// ala.occurences core module
"occurences": {
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
// total records found
"count": 107,
// occurences count by species: common name
// note, that many species have no common name
"common_name": {
"Acacia Hedge": 4,
"Australian Golden Wattle": 13,
"Black Wattle": 16,
...
},
// occurences count by species: taxonomy name
"taxon_name": {
"Acacia": 1,
"Acacia acinacea": 12,
....
}
},
// ala.species aggregator
"species": {
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
// species module - species are indexed by taxonomy name
"species": {
"Acacia": {
// ala guid for further lookups
"guid": "urn:lsid:biodiversity.org.au:apni.taxon:295861",
"common_name": "Wattle",
// native species
"isAustralian": "recorded",
"image": "http:\/\/bie.ala.org.au\/repo\/1009\/24\/250623\/raw.jpg",
"thumbnail": "http:\/\/bie.ala.org.au\/repo\/1009\/24\/250623\/thumbnail.jpg"
// density map module
"densityMap": {
// Australia - png image
"australia": "http:\/\/biocache.ala.org.au\/ws\/density\/map?q=Acacia"
}
},
"Acacia acinacea": {
"guid": "urn:lsid:biodiversity.org.au:apni.taxon:295874",
"common_name": "Gold-dust Acacia",
"isAustralian": "recorded",
"image": "http:\/\/bie.ala.org.au\/repo\/1124\/193\/1933412\/raw.jpg",
"thumbnail": "http:\/\/bie.ala.org.au\/repo\/1124\/193\/1933412\/thumbnail.jpg"
"densityMap": {
"australia": "http:\/\/biocache.ala.org.au\/ws\/density\/map?q=Acacia+acinacea"
}
},
....
}
}
}
```

## ala.species

* returns information for a species

### GET

```
/ala.species.php?taxon_name=Acacia+penninervis
```

Params:

* `taxon_name`: taxonomy name
* `dump` (optional, debug!): pretty-dumps json for debugging

### Example response:

```javascript
{
"ala": {
"species": {
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
"species": {
"Acacia penninervis": {
// taxonomy concept id: see ala.species.details
"guid": "urn:lsid:biodiversity.org.au:apni.taxon:298661",
"common_name": "Hickory",
"isAustralian": "recorded",
"image": "http:\/\/bie.ala.org.au\/repo\/1051\/187\/1874162\/raw.jpg",
"thumbnail": "http:\/\/bie.ala.org.au\/repo\/1051\/187\/1874162\/thumbnail.jpg",
"densityMap": {
"australia": "http:\/\/biocache.ala.org.au\/ws\/density\/map?q=Acacia+penninervis"
}
}
}
}
}
}
```

## ala.species.details

* returns details about a species: description, images, conservation status, links classifications etc

### GET

```javascript
// Acacia penninervis
/ala.species.details.php?guid=urn:lsid:biodiversity.org.au:apni.taxon:298661&dump=1
```

Params:

* `guid`: The guid for the taxon concept, returned by **ala.species** lookup
* `dump` (optional, debug!): pretty-dumps json for debugging

### Example response:

```javascript
{
"ala": {
"species": {
"details": {,
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
"name": "Acacia penninervis",
"isAustralian": true,
// properties are string or null
"classification": {
"kingdom": "Plantae",
"phylum": "Charophyta",
"class_": "Equisetopsida",
"order": "Fabales",
"family": "Fabaceae",
"genus": "Acacia",
"species": "Acacia penninervis"
...
},
// array of common_names
"commonNames": [
"Hickory",
"Hickory Wattle",
"Mountain Hickory",
"Native Hickory",
"Mountain Hickory"
...
],
// conservation statuses by region empty array if no data, seea populated example below
"conservationStatuses": [
],
"descriptions": {
"Description": "Erect or spreading shrub or tree mostly 2\u20138 m high; bark finely or deeply fissured, dark grey; branchlets \u00b1 terete, glabrous, sometimes pruinose.",
"Distribution": "Widespread, especially in inland divisions.",
"Flowering Season": "Flowers throughout year"
...
},
// empty array if no data
"references": [
{
"source": "Wikipedia",
"title": "Acacia penninervis",
"url": "http:\/\/en.wikipedia.org\/wiki\/Acacia_penninervis"
}
...
],
// empty array if no data
"images": [
{
"source": "Encyclopedia of Life",
"contentType": "image\/jpeg",
"thumbnail": "http:\/\/bie.ala.org.au\/repo\/1051\/187\/1874162\/thumbnail.jpg",
"title": "Acacia penninervis"
},
...
]
}
}
}
}
```

### conservation data status example:

example of pouplated array for an endangered species: Macrotis lagotis (Bilby): `/ala.species.details.php?guid=urn:lsid:biodiversity.org.au:afd.taxon:3814d122-c95f-467f-a3a2-2b269931b74f&dump=1`

```javascript
{
"ala": {
"species": {
"details": {
// ... other properties ...

"conservationStatuses": {
"New South Wales": {
"system": "Threatened Species Conservation Act 1995",
"status": "Presumed Extinct",
"rawCode": "E4"
},
"Australia": {
"system": "The Environment Protection and Biodiversity Conservation Act 1999",
"status": "Vulnerable",
"rawCode": null
},
"Queensland": {
"system": "Nature Conservation Act 1992",
"status": "Endangered",
"rawCode": "E"
},
"South Australia": {
"system": "National Parks and Wildlife Act 1972",
"status": "Vulnerable",
"rawCode": "V"
},
"Northern Territory": {
"system": "Territory Parks and Wildlife Conservation Act 2000",
"status": "Vulnerable",
"rawCode": null
},
"Western Australia": {
"system": "Wildlife Conservation Act 1950",
"status": "Vulnerable",
"rawCode": "VU"
}
},

// ... other properties ...
}
}
}
}

```

## ala.explore.groups

* returns counts of all species groups for a given location

### GET

```
/ala.explore.groups.php?lat=-34.928726&lon=138.59994&radius=5&dump=1
```

Params:

* `lat`: latitude
* `lon`: longitude
* `rad`: radius
* `dump` (optional, debug!): pretty-dumps json for debugging

### Example response:

```javascript
{
"ala": {
"explore": {
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
//all species
"count": 105858,
//sorted by groups
"groups": {
" Animals": 99633,
" Mammals": 341,
" Birds": 93738,
" Reptiles": 135,
" Amphibians": 498,
" Fish": 173,
" Molluscs": 148,
" Arthropods": 4558,
" Crustaceans": 13,
" Insects": 3759,
" Plants": 5405,
" Bryophytes": 29,
" Gymnosperms": 15,
" Ferns And Allies": 21,
" Angiosperms": 5304,
" Monocots": 1674,
" Dicots": 3630,
" Fungi": 116,
" Chromista": 18,
" Protozoa": 8,
" Bacteria": 0,
" Algae": 13
}
}
}
}
```

* responds with "_status": 400 and no data when included as module into `POST ala.occurrences`. ALA api doesn't support geo polygons for groups.

## ala.explore.group

* returns counts of all species groups for a given location

### GET

```
/ala.explore.group.php?group_name=Birds&lat=-34.928726&lon=138.59994&radius=5
```

Params:

* `group_name`: zoological name of the species group, allowecd names: see example response for *ala.explore.groups*
* `lat`: latitude
* `lon`: longitude
* `rad`: radius
* `dump` (optional, debug!): pretty-dumps json for debugging

### Example response:

```javascript
{
"ala": {
"explore": {
"group": {
// curl response status
"_status": 200,
// messages may be logged when _status != 200
"_errors": [],
"count": {
"total": 93738,
"distinct": 380
}
}
}
}
}
```
* `_status` is set to `400` if group name is invalid
* responds with "_status": 400 and no data when included as module into `POST ala.occurrences`. ALA api doesn't support geo polygons for groups.

# Mongo Cache

A simple Mongo cache api is in development and is located in `\Api\Cache.php`. Currently this Api requires a local Mongo server which you need to set up.

TODO:

* expiry
* remote Mongo
* hook up to `ala.species`