jibjib-api

README

jibjib-api

Go REST API to receive input from the JibJib Android App, query the model and send those information back to the App.

Repo layout

The complete list of JibJib repos is:

• jibjib: Our Android app. Records sounds and looks fantastic.
• deploy: Instructions to deploy the JibJib stack.
• jibjib-model: Code for training the machine learning model for bird classification
• jibjib-api: Main API to receive database requests & audio files.
• jibjib-data: A MongoDB instance holding information about detectable birds.
• jibjib-query: A thin Python Flask API that handles communication with the TensorFlow Serving instance.
• gopeana: A API client for Europeana, written in Go.
• voice-grabber: A collection of scripts to construct the dataset required for model training

Install

Docker

See deploy instructions.

Compile yourself

If you didn't clone the repo, go get the package and the main.go:

go get github.com/gojibjib/jibjib-api/pkg
cd $GOPATH/src/github.com/gojibjib/jibjib-api
wget https://raw.githubusercontent.com/gojibjib/jibjib-api/master/meta/main.go 

Compile it:

CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

Setup jibjib-data.

Start the API:

export JIBJIB_DB_URL=read:read@localhost/birds
./app

API Documentation

Endpoints

Endpoint	Method	Comment
/	GET	Answers with a basic "Pong" response
/ping	GET	Answers with a basic "Pong" response
/birds/dummy	GET	Sends a JSON Response with randomized IDs and accuracies for testing
/birds/all	GET	Retrieves all bird information, without descriptions
/birds/{id:[0-9]+}	GET	Retrieves bird information by ID. Use query string desc_de=false and desc_en=false to omit description fields.
/detect/binary	POST	Send a MP4 file to the API to start querying the ML model for bird voice recognition. File needs to be send in binary format and with the Header Content-Type: application/octet-stream set.

Response format

{
    "status": <int>,
    "message": <string>,
    "count": <int>,
    "data": {...} | null
}

Examples

curl "http://localhost:8080/ping"
{
    "status":200,
    "message":"Pong",
    "count":0,
    "data":null
}

curl "htttp://localhost:8080/birds/1"
{
    "status":200,
    "message":"Bird found",
    "count":1,
    "data": {
        "id":1,
        "name":"Cuculus canorus",
        "genus":"Cuculus",
        "species":"canorus",
        "title_de":"Kuckuck",
        "title_en":"Common cuckoo",
        "desc_de":"...omitted...",
        "desc_en":"...omitted..."
    }
}

curl "htttp://localhost:8080/birds/1?desc_de=false&desc_en=false"
{
    "status":200,
    "message":"Bird found",
    "count":1,
    "data": {
        "id":1,
        "name":"Cuculus canorus",
        "genus":"Cuculus",
        "species":"canorus",
        "title_de":"Kuckuck",
        "title_en":"Common cuckoo",
        "desc_de":"",
        "desc_en":""
    }
}

# For now, only mp4 files are being accepted
curl -H 'Content-Type: application/octet-stream' -X POST --data-binary @larus_canus_3.mp4 http://localhost:8081/detect/binary
{
  "message": "Detection successful",
  "status": 200,
  "count": 3,
  "data": [
    {
      "accuracy": 0.6470588235294118,
      "id": 110
    },
    {
      "accuracy": 0.17647058823529413,
      "id": 7
    },
    {
      "accuracy": 0.17647058823529413,
      "id": 30
    }
  ]
}