DigiBird API: on the fly collection integration

Note: this project is no longer in active development and the repository has been archived. The results of the DigiBird project have been documented in the paper: DigiBird: On The Fly Collection Integration Supported By The Crowd.

DigiBird is a system that integrates cultural heritage data on the fly. This repository contains code for the API code, code for the client can found in another repository.

Example API call

Quick example querying for sounds of a Magpie from Xeno-canto:

http://www.digibird.org/api/objects?platform=xeno-canto&genus=Pica&species=pica

This will give you a rather complex JSON-LD response:

{
  "@context": {
    "dcterms": "http://purl.org/dc/terms/",
    "dctype": "http://purl.org/dc/dcmitype/",
    "ore": "http://www.openarchives.org/ore/terms/",
    "edm": "http://www.europeana.eu/schemas/edm/",
    "dcterms:type": {
      "@type": "@id"
    },
    "edm:aggregatedCHO": {
      "@type": "@id"
    },
    "edm:hasView": {
      "@type": "@id"
    }
  },
  "@graph": [
    {
      "@id": "http://www.xeno-canto.org/276751/aggregation",
      "@type": "ore:Aggregation",
      "edm:aggregatedCHO": {
        "@id": "http://www.xeno-canto.org/276751",
        "@type": "edm:ProvidedCHO"
      },
      "edm:hasView": {
        "@id": "http://www.xeno-canto.org/276751/download",
        "@type": "edm:WebResource",
        "dcterms:type": "dctype:Sound"
      }
    }
  ]
}

Content negotiation can be used to request other formats.

API Documentation

The base of the api is http://www.digibird.org/api/

Media API

If you want to request media you can use this url: http://www.digibird.org/api/objects You can use the following parameters for media:

Platform

The platform you would like to get media from. Supported platforms right now:

• Xeno-canto (id: xeno-canto) - Bird sounds
• Rijksmuseum (id: rijksmuseum) - Artworks, substring matching only
• Accurator (id: accurator) - Rijksmuseum artworks annotated with scientific names
• Nederlands Soorten Register (id: soortenregister) - Images of birds

You can request media from multiple platforms by adding multiple parameters: http://www.digibird.org/api/objects?platform=xeno-canto&platform=soortenregister

Omitting the platform parameter results in querying all available platforms

Genus

This parameter is used to specify the genus of the specimens you would like to see media of: http://www.digibird.org/api/objects?platform=xeno-canto&genus=Pica

It is not yet verified whether the genus/species exist, this might be implemented at a later point. Now an empty result set will be returned.

Species

This parameter is used in combination with the genus parameter to specify the search query: http://www.digibird.org/api/objects?platform=xeno-canto&genus=Pica&species=pica

For now either the genus or the genus plus the species is required, at a later point we will support using common name queries.

Annotations API

If you want to request the latest contributions on a crowdsourcing platform you can use this url: http://www.digibird.org/api/annotations You can use the following parameters for annotations:

Platform

The platform you would like to get media from. Supported platforms right now:

• Waisda? (id: waisda) - Videos and their corresponding tags
• Accurator (id: accurator) - Rijksmuseum artworks annotated with scientific names

An example of the json-ld that is returned:

{
  "@graph": [
    {
      "@id":"http://hdl.handle.net/10934/RM0001.collect.89134%3Aaggregation",
      "@type":"ore:Aggregation",
      "edm:aggregatedCHO":{
        "@id":"http://purl.org/collections/nl/rma/RP-P-1878-A-710",
        "@type":"edm:ProvidedCHO",
        "dc:creator":"Visscher, Claes Jansz. (II)",
        "dc:title":"Kroonkraanvogel tussen twee struisvogels"
      },
      "edm:isShownBy":{
        "@id":"http://lh5.ggpht.com/iuEgYC__Qh4QLIRtiwBF5PBq3WIZAgQEF26LuVNmLEgDISluVuPGiDv",
        "@type":"edm:WebResource",
        "dcterms:type":"dctype:Image"
      }
    }
    {
      "@id":"http://localhost/annotation/instances/id_09d7d022c762ba830386ee66de8c8250635bb2de",
      "@type":"oa:Annotation",
      "oa:hasTarget":"http://purl.org/collections/nl/rma/RP-P-1878-A-710",
      "oa:hasBody":"struisvogel",
      "oa:annotatedAt":"2016-10-31T16:34:33+01:00"
    }
  ]
}

The response contains two elements, an object and an annotation of the object. This model conforms to the web annotation model.

Content negotiation

Supported media-types:

• application/ld+json
• application/json
• text/turtle
• application/n-quads

If you set the accept-header to json, it will give you a plain json response:

curl -H "Accept: application/json" "http://www.digibird.org/api/objects?platform=soortenregister&genus=Pica&species=pica"

The reply will be formatted like this:

{"results": [
  {"url":"http://www.nederlandsesoorten.nl/464942884_2091265265",
   "media_url":"http://images.naturalis.nl/original/132623.jpg",
   "media_type":”Image"
  }
]}