-
Notifications
You must be signed in to change notification settings - Fork 3
Home
Welcome to the biocaching-api-doc wiki!
This page documents the Biocaching REST-based APIs. To access Biocaching through the API you also need a username and a password. If you have that, you can invoke the API with curl on the command line:
curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
-X POST "http://api.biocaching.com:82/users/sign_in" \
-d '{"user" : { "email" : "[email protected]", "password" : "<PASSWORD>"}}' \If successful, the command will return something like this:
{"id":1,"email":"[email protected]","created_at":"2016-02-16T12:36:44.000Z",
"updated_at":"2016-02-17T13:22:08.320Z","authentication_token":"zCC868dPzS2Gp1y-UE1M"}The token can then be used to invoke further services, for example get a taxon:
curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'X-User-Email: [email protected]' -H 'X-User-Token: zCC868dPzS2Gp1y-UE1M' \
-X GET "http://api.biocaching.com:82/taxa/475?fields=all"
Also see the example programs provided. All requests must use Content-Type application/json and must accept a response in the same content type.
POST /users/sign_in
| Parameter | Description |
|---|---|
| user[email] | The user's email address |
| user[password] | The user's password |
POST /users
| Parameter | Description |
|---|---|
| user[email] | The user's email address |
| user[password] | The user's password |
| user[password_confirmation] | The user's password repeated |
The Taxa services give access to the species database.
GET /taxa
Retrieves taxa in json format.
Called with no extra parameters, this service returns the taxa with rank "kingdom".
| Parameter | Description |
|---|---|
| from | Return a subset of the taxa, start at 'from', default = 0 |
| size | Return 'size' number of taxa, default = 10 |
| parent_id | Return taxa that are immediate children of another taxa. If omitted, return taxa on the highest level (the kingdoms: animalia, plantae and fungi) |
| fields | If omitted, only a subsets of the available fields are included in the response. Pass value "all" to have all available fields returned |
| region | Only return taxa that are found in a specific region. E.g. region=nor |
Get taxa without parents (the kingdoms):
GET /taxa
Get all 35 taxa in the animal kingdom:
GET /taxa?parent_id=1&size=40
Get all taxa in the chordata phylum:
GET /taxa?parent_id=11&size=40
GET /taxa/<taxa_id>
Retrieves one specific taxa as JSON on this format:
{
"total": 1,
"max_score": 1.0,
"number_of_hits": 1,
"hits": [
{
"_index": "taxa",
"_type": "taxon",
"_id": "2248",
"_score": 1.0,
"_source": {
"observations_count": 5,
"hidden": false,
"other_pictures": [
{
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/754/original/Mustela_erminea.jpg?1464254878",
"thumb": "/system/taxon_pictures/pictures/000/000/754/thumb/Mustela_erminea.jpg?1464254878",
"medium": "/system/taxon_pictures/pictures/000/000/754/medium/Mustela_erminea.jpg?1464254878"
},
"credits": [
{
"full_name": "Steve Hillebrand, USFWS",
"role": "photographer",
"homepage": ""
},
{
"full_name": "Wikimedia Commons",
"role": "provider",
"homepage": "http://commons.wikimedia.org/"
}
],
"picture_id": 754,
"rights_holder": null,
"title": "File:Mustela erminea.jpg",
"source_url": "http://commons.wikimedia.org/wiki/File:Mustela_erminea.jpg",
"license_url": "http://creativecommons.org/publicdomain/mark/1.0/",
"primary": false
},
{
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/755/original/4894.jpeg?1464254882",
"thumb": "/system/taxon_pictures/pictures/000/000/755/thumb/4894.jpeg?1464254882",
"medium": "/system/taxon_pictures/pictures/000/000/755/medium/4894.jpeg?1464254882"
},
"credits": [
{
"full_name": "Gerald and Buff Corsi",
"role": "photographer",
"homepage": "http://calphotos.berkeley.edu/cgi/photographer_query?where-name_full=Gerald+and+Buff+Corsi&one=T"
},
{
"full_name": "CalPhotos",
"role": "provider",
"homepage": "http://calphotos.berkeley.edu/"
}
],
"picture_id": 755,
"rights_holder": "2007 California Academy of Sciences",
"title": null,
"source_url": "http://calphotos.berkeley.edu/cgi/img_query?seq_num=71233&one=T",
"license_url": "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"primary": false
}
],
"taxonomy_ranks": {
"phylum": "chordata",
"genus": "mustela",
"species": "erminea",
"family": "mustelidae",
"kingdom": "animalia",
"class": "mammalia",
"order": "carnivora"
},
"scientific_name": "mustela erminea",
"source": {
"source_database": {
"name": "ITIS Global: The Integrated Taxonomic Information System",
"authors_and_editors": "Orrell T. (custodian)",
"id": 2,
"uri": "http://www.itis.gov;\nhttp://www.cbif.gc.ca/acp/eng/itis/search (Canada)",
"uri_scheme": "http"
},
"taxonomy": "Species 2000 & ITIS Catalogue of Life: 2013 Annual Checklist"
},
"taxonomy_credit": "Species 2000 & ITIS Catalogue of Life: 2013 Annual Checklist",
"eol_page_link": "http://eol.org/328587?action=overview&controller=taxa",
"names": {
"nob": [
"røyskatt"
],
"fra": [
"hermine"
],
"nno": [
"røyskatt"
],
"eng": [
"Ermine"
]
},
"parent_id": 2238,
"in_regions": [
"nor"
],
"primary_picture": {
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/753/original/0047.jpeg?1464254876",
"thumb": "/system/taxon_pictures/pictures/000/000/753/thumb/0047.jpeg?1464254876",
"medium": "/system/taxon_pictures/pictures/000/000/753/medium/0047.jpeg?1464254876"
},
"credits": [
{
"full_name": "Gerald and Buff Corsi",
"role": "photographer",
"homepage": "http://calphotos.berkeley.edu/cgi/photographer_query?where-name_full=Gerald+and+Buff+Corsi&one=T"
},
{
"full_name": "CalPhotos",
"role": "provider",
"homepage": "http://calphotos.berkeley.edu/"
}
],
"picture_id": 753,
"rights_holder": "2008 California Academy of Sciences",
"title": null,
"source_url": "http://calphotos.berkeley.edu/cgi/img_query?seq_num=264425&one=T",
"license_url": "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"primary": true
},
"col_taxon_id": 21936091,
"rank": "species",
"id": 2248,
"languages_iso": [
"eng",
"fra",
"nob",
"nno"
],
"slug": "animalia-chordata-mammalia-carnivora-mustelidae-mustela-erminea"
}
}
]
}| Parameter | Description |
|---|---|
| fields | If omitted, only a subsets of the available fields are included in the response. Pass value "all" to have all available fields returned |
Search for taxa
GET /taxa/search?term=<search_term>
Search, by name, for taxa in a specific taxonomy. Taxa is returned in JSON in this format (only one hit in this example):
{
"total": 1,
"max_score": 0.8272788,
"number_of_hits": 1,
"hits": [
{
"_index": "taxa",
"_type": "taxon",
"_id": "2248",
"_score": 0.8272788,
"_source": {
"names": {
"nob": [
"røyskatt"
]
},
"parent_id": 2238,
"primary_picture": {
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/753/original/0047.jpeg?1464254876",
"thumb": "/system/taxon_pictures/pictures/000/000/753/thumb/0047.jpeg?1464254876",
"medium": "/system/taxon_pictures/pictures/000/000/753/medium/0047.jpeg?1464254876"
},
"credits": [
{
"full_name": "Gerald and Buff Corsi",
"role": "photographer",
"homepage": "http://calphotos.berkeley.edu/cgi/photographer_query?where-name_full=Gerald+and+Buff+Corsi&one=T"
},
{
"full_name": "CalPhotos",
"role": "provider",
"homepage": "http://calphotos.berkeley.edu/"
}
],
"picture_id": 753,
"rights_holder": "2008 California Academy of Sciences",
"title": null,
"source_url": "http://calphotos.berkeley.edu/cgi/img_query?seq_num=264425&one=T",
"license_url": "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"primary": true
},
"other_pictures": [
{
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/754/original/Mustela_erminea.jpg?1464254878",
"thumb": "/system/taxon_pictures/pictures/000/000/754/thumb/Mustela_erminea.jpg?1464254878",
"medium": "/system/taxon_pictures/pictures/000/000/754/medium/Mustela_erminea.jpg?1464254878"
},
"credits": [
{
"full_name": "Steve Hillebrand, USFWS",
"role": "photographer",
"homepage": ""
},
{
"full_name": "Wikimedia Commons",
"role": "provider",
"homepage": "http://commons.wikimedia.org/"
}
],
"picture_id": 754,
"rights_holder": null,
"title": "File:Mustela erminea.jpg",
"source_url": "http://commons.wikimedia.org/wiki/File:Mustela_erminea.jpg",
"license_url": "http://creativecommons.org/publicdomain/mark/1.0/",
"primary": false
},
{
"urls": {
"original": "/system/taxon_pictures/pictures/000/000/755/original/4894.jpeg?1464254882",
"thumb": "/system/taxon_pictures/pictures/000/000/755/thumb/4894.jpeg?1464254882",
"medium": "/system/taxon_pictures/pictures/000/000/755/medium/4894.jpeg?1464254882"
},
"credits": [
{
"full_name": "Gerald and Buff Corsi",
"role": "photographer",
"homepage": "http://calphotos.berkeley.edu/cgi/photographer_query?where-name_full=Gerald+and+Buff+Corsi&one=T"
},
{
"full_name": "CalPhotos",
"role": "provider",
"homepage": "http://calphotos.berkeley.edu/"
}
],
"picture_id": 755,
"rights_holder": "2007 California Academy of Sciences",
"title": null,
"source_url": "http://calphotos.berkeley.edu/cgi/img_query?seq_num=71233&one=T",
"license_url": "http://creativecommons.org/licenses/by-nc-sa/3.0/",
"primary": false
}
],
"rank": "species",
"scientific_name": "mustela erminea",
"source": {
"source_database": {
"name": "ITIS Global: The Integrated Taxonomic Information System",
"authors_and_editors": "Orrell T. (custodian)",
"id": 2,
"uri": "http://www.itis.gov;\nhttp://www.cbif.gc.ca/acp/eng/itis/search (Canada)",
"uri_scheme": "http"
},
"taxonomy": "Species 2000 & ITIS Catalogue of Life: 2013 Annual Checklist"
},
"id": 2248
},
"highlight": {
"scientific_name": [
"mustela <span class=\"highlight\">ermine</span>a"
]
}
}
],
"aggregations": {
"24": {
"doc_count": 1
},
"25": {
"doc_count": 0
},
"26": {
"doc_count": 0
}
},
"collection": {
"parent_id": null,
"id": 27,
"names": [
{
"name": "Alle arter",
"language_iso": "nob"
}
],
"children": [
{
"id": 24,
"names": [
{
"name": "Dyr",
"language_iso": "nob"
}
]
},
{
"id": 25,
"names": [
{
"name": "Planter",
"language_iso": "nob"
}
]
},
{
"id": 26,
"names": [
{
"name": "Sopp",
"language_iso": "nob"
}
]
}
]
}
}| Parameter | Description |
|---|---|
| term | Search for search_term in scientific and common names of taxa with rank genus, species and infraspecific. |
| Parameter | Description |
|---|---|
| from | Return a subset of the taxa, start at 'from', default = 0 |
| size | Return 'size' number of taxa, default = 10 |
| below_rank, below_rank_value | return only taxa below a certain rank in the taxonomy. |
| fields | If omitted, only a subsets of the available fields are included in the response. Pass value "all" to have all available fields returned, pass value "autocomplete" to return values on this form (with search term "iland"): |
| region | Only return taxa that are found in a specific region. For now, only region "nor" is available |
| languages | Only return taxa that have common names in one of the specified languages (ISO 639-2), default is "eng" |
| collection_id | only return taxa within a collection |
| include_empty_collections | include child-collections in the aggregations even if they have no species |
When passing value "autocomplete" for the 'fields' parameter, the service will return json formatted like this (the values are: common name, common name with search term highlighted, scientific name with search term highlighted, COL taxon id, URL of the taxon thumbnail):
[
[
"niland",
"n<span class=\"highlight\">iland</span>",
"alopochen aegyptiaca",
60959,
"/system/taxon_pictures/pictures/000/000/125/thumb/7108163987_fc15821473_o.jpg?1459493680"
],
[
"siland",
"s<span class=\"highlight\">iland</span>",
"mergus serrator",
61218,
"/system/taxon_pictures/pictures/000/000/230/thumb/5582216076_dd478bf06f_o.jpg?1459494081"
]
]Get the 5 first species in the mammalia class (mammals):
GET /taxa/search?below_rank=class&below_rank_value=mammalia&size=5
Get the 5 next species in the mammalia class (mammals):
GET /taxa/search?below_rank=class&below_rank_value=mammalia&size=5&from=5
Search for birds named something with "meis" in Norwegian bokmål or nynorsk, return at most 10 results:
GET /taxa/search?below_rank=class&below_rank_value=aves&size=10&term=meis&languages=nob,nno
When fields is not "autocomplete" the taxa search service returns json on this format (size-parameter is set to 0 in the example):
{
"total": 7,
"max_score": 0.0,
"number_of_hits": 0,
"hits": [
],
"aggregations": {
"22": {
"doc_count": 1
},
"23": {
"doc_count": 5
},
"6": {
"doc_count": 1
}
},
"collection": {
"parent_id": 27,
"id": 24,
"names": [
{
"name": "Dyr",
"language_iso": "nob"
}
],
"children": [
{
"id": 6,
"names": [
{
"name": "Pattedyr",
"language_iso": "nob"
}
]
},
{
"id": 22,
"names": [
{
"name": "Fugler",
"language_iso": "nob"
}
]
},
{
"id": 23,
"names": [
{
"name": "Fisk",
"language_iso": "nob"
}
]
}
],
"parents": [
{
"id": 27,
"names": [
{
"name": "Alle arter",
"language_iso": "nob"
}
]
}
]
}
}In the aggregation object, the ids refers to the ids of the children of the current collection. This can then be used to present after searching: Pattedyr (1) Fugler (1) Fisk (5)
(indicates number of hits in each child-collection).
Get one observation:
GET /observations/<id>
Observations are returned in JSON in this format:
{
"observation": {
"id": 154,
"observed_at": "2016-08-04T21:49:00.000+02:00",
"user_id": 1,
"comment": "",
"created_at": "2016-08-04T21:49:57.000+02:00",
"updated_at": "2016-08-04T21:49:57.000+02:00",
"what3words": "redefined.assets.warm",
"individual_count": null,
"sex": "",
"life_stage": "",
"country": "United Kingdom",
"county": "Highland",
"municipality": "Perth and Kinross",
"locality": "Alvie",
"geonames_id": "2657386",
"coordinate_uncertainty_in_meters": null,
"is_public": true,
"location_id": "http://sws.geonames.org/2657386",
"location": {
"lat": "57.148955",
"lon": "-3.912597"
},
"tags": [
"hareid",
"bjorn"
],
"tags_suggest": {
"input": [
"hareid",
"bjorn"
]
},
"verified_by": null,
"points": 1,
"comments_count": 3,
"taxon": {
"id": 699,
"scientific_name": "cervidae",
"all_common_names": {
"nob": [
"hjortefamilien"
],
"nno": [
"hjortefamilien"
]
}
},
"likes": [
],
"other_pictures": [
]
},
"users": {
"1": {
"id": "1",
"email": "[email protected]",
"firstname": "Bjørn",
"lastname": "Hjelle",
"displayname": "Bjørn",
"name": "Bjørn",
"picture": {
"thumb": "/system/pictures/pictures/000/000/143/thumb/greylag_3.JPG?1467291918",
"medium": "/system/pictures/pictures/000/000/143/medium/greylag_3.JPG?1467291918",
"original": "/system/pictures/pictures/000/000/143/original/greylag_3.JPG?1467291918"
}
}
}
}
Retrieve observations
GET /observations
Get a listing of observations
| Parameter | Description |
|---|---|
| user_id | Get observations that has been reported by a user. Without this, all observations are returned. |
| from | Return a subset of the observations, start at 'from', default = 0 |
| size | Return 'size' number of observations, default = 10 |
| sort_field | Set sort field, default is "created_at". If sort_field is "distance" it is not actually sorted by distance. In stead an Elasticsearch sort function us used to influence the relevancy score of the search results. |
| sort_order | Set sort order to "asc" or "desc", default is "desc". Is not used if sort_field is "distance". |
| taxon_id | Only return observations of a specific taxa |
| latitude | Latitude |
| longitude | Longitude |
| distance | Get observations from within distance from the location given by the latitude and longitude coordinates. See this for allowed formats: https://www.elastic.co/guide/en/elasticsearch/reference/1.4/common-options.html#distance-units |
| top_left | Top left corner of a bounding_box, specified as lon,lat (as in GeoJSON), e g: 14.34,65.3 |
| bottom_right | Bottom right corner of a bounding_box, specified as lon,lat (as in GeoJSON), e g: 16.34,62.3 |
| tag_list | A space separated list of tags. Only return observations with these tags |
| draft_only | Only return observations that have status 'draft' |
| public_only | Only return observations that have status 'public' |
| verified_only | Only return observations that have been verified |
| following_only | Only return observations created by users the logged in user follows (and his own) |
| from_time | Only return observations with observed_at after this time. Format is ISO8601, e g "2014-07-22T23:49:40.000Z". If the parameter is not properly formatted, the parameter will be ignored |
| to_time | Only return observations with observed_at before this time. Format is ISO8601, e g "2014-07-22T23:49:40.000Z". If the parameter is not properly formatted, the parameter will be ignored |
Note: top_left and bottom_right will not be used if latitude, longitude and distance are specified.
Get all observations with 20km from a location:
GET /observations?latitude=61&longitude=12.4&distance=20km
Observations are returned in JSON in the format (only one observation returned in this example). Note the last item, "users", which can be used to look up information about the users mentioned by user_id in the observations returned.
{
"total": 1,
"max_score": null,
"number_of_hits": 1,
"hits": [
{
"_index": "observations",
"_type": "observation",
"_id": "32",
"_score": null,
"_source": {
"id": 32,
"observed_at": "2016-05-11T10:43:21.000Z",
"user_id": 1,
"comments": [
],
"created_at": "2016-05-11T10:43:27.000Z",
"updated_at": "2016-05-11T10:43:27.000Z",
"what3words": "slyly.creatures.strumming",
"individual_count": 5,
"sex": "3 males, 2 females",
"life_stage": "4 adults, 1 juvenile",
"country": "Sweden",
"county": "Västerbotten",
"municipality": "Hattfjelldal",
"locality": "Stikkenjokk",
"geonames_id": "2674321",
"coordinate_uncertainty_in_meters": 30,
"location_id": "http://sws.geonames.org/2674321",
"location": {
"lat": "65.123",
"lon": "14.234"
},
"comments_count": 3,
"taxon": {
"id": 61057,
"scientific_name": "anser anser",
"all_common_names": {
"eng": [
"Greylag Goose"
],
"nob": [
"grågås"
],
"nno": [
"grågås"
]
}
},
"likes": [
{
"id": 26,
"user_id": 1,
"user": {
"email": "[email protected]"
}
}
],
"primary_picture": {
"id": 12,
"primary": true,
"urls": {
"medium": "/system/pictures/pictures/000/000/012/medium/greylag_2.jpg?1462964727",
"thumb": "/system/pictures/pictures/000/000/012/medium/greylag_2.jpg?1462964727",
"original": "/system/pictures/pictures/000/000/012/original/greylag_2.jpg?1462964727"
},
"likes": [
{
"id": 27,
"user_id": 1,
"user": {
"email": "[email protected]"
}
}
]
},
"other_pictures": [
{
"id": 11,
"primary": false,
"urls": {
"medium": "/system/pictures/pictures/000/000/011/medium/greylag_goose.jpg?1462963403",
"thumb": "/system/pictures/pictures/000/000/011/medium/greylag_goose.jpg?1462963403",
"original": "/system/pictures/pictures/000/000/011/original/greylag_goose.jpg?1462963403"
},
"likes": [
]
}
]
},
"sort": [
1462963407000
]
}
],
"users":
{"1":
{"id": "1", "email": "[email protected]", "firstname": "Bjørn", "lastname": "Hjelle", "displayname": "Bjørn"}
}
}POST /observations
Creates an observation with date/time, location, a taxon and a picture.
| Parameter | Description |
|---|---|
| taxon_id | The id of the taxon observed, as returned by the taxa-servies |
| observed_at | Date and time in ISO 8601 format, e g "2016-02-19 13:50:58 +0100" |
| latitude | The latitude of the location |
| longitude | The longitude of the location |
| coordinate_uncertainty_in_meters | Coordinate uncertainty in meters |
| comment | A free text comment |
| picture_attributes[picture[content_type]] | Content type of the picture, e g "image/jpg" |
| picture_attributes[picture[headers]] | |
| picture_attributes[picture[original_filename]] | |
| picture_attributes[picture[tempfile]] | |
| picture_attributes[primary] | Set to "true" if this will be the observations 'primary' picture. Default is false. |
| individual_count | the number of individuals observed |
| sex | sex of the observed indoviduals. Can be specified like: "2 females, 3 males", or just "females" if all are females |
| life_stage | life stage of the individuals. E g: "eggs", "juveniles", "2 adults, 1 juvenile" |
| tag_list | A space separated list of tags that will be added to the observation |
| add_tags_from_setting | Set to "false" if you do not want the tags from the user's settings added automatically |
| is_public | set if the observation should be visible to other users, default is true |
The parameters must be supplied as the content of the HTTP POST in a JSON hash with key "observation". See example programs for details (create_observation.rb)
PUT /observations/<observation_id>
Updates an observation. The parameters are the same as the create service.
| Parameter | Description |
|---|---|
| taxon_id | The id of the taxon observed, as returned by the taxa-servies |
| observed_at | Date and time in ISO 8601 format, e g "2016-02-19 13:50:58 +0100" |
| latitude | The latitude of the location |
| longitude | The longitude of the location |
| coordinate_uncertainty_in_meters | Coordinate uncertainty in meters |
| comments | A free text comment |
| picture_attributes[picture[content_type]] | Content type of the picture, e g "image/jpg" |
| picture_attributes[picture[headers]] | |
| picture_attributes[picture[tempfile]] | |
| picture_attributes[primary] | Set to "true" if this will be the observations 'primary' picture. Default is false. |
| individual_count | the number of individuals observed |
| sex | sex of the observed indoviduals. Can be specified like: "2 females, 3 males", or just "females" if all are females |
| life_stage | life stage of the individuals. E g: "eggs", "juveniles", "2 adults, 1 juvenile" |
| tag_list | A space separated list of tags that will be added to the observation |
| is_public | set if the observation should be visible to other users, default is true |
DELETE /observations/<observation_id>
The user must own the observation to do this. Observations with status draft are only available to the user herself.
POST /observations/<observation_id>/draft
The user must own the observation to do this. Observations with status public are visible to all users.
POST /observations/<observation_id>/public
Verify that an observation specifies the correct species. For now only admin users can verify observations. This will add an element, "verified_by" to the observation that includes the user_id of the user who verified, and the exact time when it was done.
POST /observations/<observation_id>/verify
To add a like for the logged on user to an observation:
POST /observations/<observation_id>/like
Adds a like for the logged on user to the observation.
POST /observations/<observation_id>/unlike
Removes a like for the logged on user from the observation.
GET /observations/<observation_id>/likes
Returns all the likes for an observation as JSON with a two-dimensional array. For each like, the user's id and name is included. If a user has a display name, it is used, otherwise the user's email is included instead:
{
"likes": [
{
"created_at": "2016-05-02T06:19:29.000Z",
"user": {
"id": 1,
"name": "Bjørn"
}
},
{
"created_at": "2016-05-02T06:36:56.000Z",
"user": {
"id": 6,
"name": "[email protected]"
}
}
]
}Observations can be commented:
POST /observations/<observation_id>/comments
| Parameter | Description |
|---|---|
| text | The comment text |
Observations can be updated by the user who created the comment, or by a user that has been granted the admin role:
PUT /observations/<observation_id>/comments/<comments_id>
| Parameter | Description |
|---|---|
| text | The comment text |
DELETE /observations/<observation_id>/comments/<comment_id>
Removes a comment from the observation.
GET /observations/<observation_id>/comments
Returns all the comments for an observation as JSON:
{
"comments": [
{
"id": 6,
"text": "dette er en kommentar",
"created_at": "2016-05-02T09:28:07.000Z",
"updated_at": "2016-05-02T09:28:07.000Z",
"user": {
"id": 1,
"name": "Bjørn"
}
},
{
"id": 9,
"text": "denne kommentaren er oppdatert",
"created_at": "2016-05-02T09:30:42.000Z",
"updated_at": "2016-05-03T07:26:20.000Z",
"user": {
"id": 1,
"name": "Bjørn"
},
"updated_by": {
"id": 1,
"name": "Bjørn"
}
}
],
"users": {
"1": {
"id": "1",
"email": "[email protected]",
"firstname": "Bjørn",
"lastname": "Hjelle",
"displayname": "Bjørn",
"name": "Bjørn",
"picture": {
"thumb": "/system/pictures/pictures/000/000/143/thumb/greylag_3.JPG?1467291918",
"medium": "/system/pictures/pictures/000/000/143/medium/greylag_3.JPG?1467291918",
"original": "/system/pictures/pictures/000/000/143/original/greylag_3.JPG?1467291918"
}
}
}
}An observation can have one primary picture and several other pictures. When an observation is created with a picture, the picture is set to be the observations primary picture. When pictures are subsequently added, they are set to be not primary. A service (described below) is available to promote a picture to become the observation's primary picture.
POST /observations/<observation_id>/pictures
| Parameter | Description |
|---|---|
| picture[content_type] | Content type of the picture, e g "image/jpg" |
| picture[headers] | |
| picture[tempfile] | |
| primary | Set to "true" if this should be the observations 'primary' picture. Default is false. |
DELETE /observations/<observation_id>/pictures/<picture_id>
No parameters.
PATCH /observations/<observation_id>/pictures/<picture_id>/primary
If the observation already has a primary picture, that picture will be set to not-primary.
No parameters.
POST /observations/<observation_id>/pictures/<picture_id>/like
No parameters.
POST /observations/<observation_id>/pictures/<picture_id>/unlike
No parameters.
This service calculates the total points for the logged in user, or for another user if user_id is passed as a parameter. Note that also the Show user-service returns a user's points. Only public observations are awarded with points, and characteristics like having identified the species, having added a picture, likes, etc. count in the calculation of points.
GET /observations/points
| Parameter | Description |
|---|---|
| user_id | The id of the user to calculate points for |
This service calculates the total points for a number of users and returns a list ordered by the score.
GET /observations/scoreboard
| Parameter | Description |
|---|---|
| count | The number of users to produce a scoreboard for. Default is 10 |
Returns JSON on this format (with count = 3):
{"points"=>
{"group_by_user"=>
{"doc_count_error_upper_bound"=>-1,
"sum_other_doc_count"=>3,
"buckets"=>
[{"key"=>"798962258", "doc_count"=>2, "sum_points"=>{"value"=>8.0}},
{"key"=>"293267324", "doc_count"=>4, "sum_points"=>{"value"=>6.0}},
{"key"=>"987556848", "doc_count"=>5, "sum_points"=>{"value"=>5.0}}]}},
"users"=>
{"293267324"=>
{"id"=>"293267324",
"email"=>"[email protected]",
"firstname"=>"Bjørn",
"lastname"=>"Hjelle",
"displayname"=>"bjorn",
"points"=>"6.0",
"game_title"=>"ladybird"},
"798962258"=>
{"id"=>"798962258",
"email"=>"[email protected]",
"firstname"=>nil,
"lastname"=>nil,
"displayname"=>nil,
"points"=>"8.0",
"game_title"=>"ladybird"},
"987556848"=>
{"id"=>"987556848",
"email"=>"[email protected]",
"firstname"=>nil,
"lastname"=>nil,
"displayname"=>"bhjelle",
"points"=>"5.0",
"game_title"=>"ladybird"}}}
Show information for a user.
GET /users/<id>
Returns JSON on this format:
{
"user": {
"id": 1,
"email": "[email protected]",
"firstname": "Bjørn",
"lastname": "Hjelle",
"displayname": "Bjørn"
},
"points": 5.0,
"followers": 0,
"following": 0,
"pictures": {
"thumb": "/system/pictures/pictures/000/000/095/thumb/greylag_goose.jpg?1464088410",
"medium": "/system/pictures/pictures/000/000/095/medium/greylag_goose.jpg?1464088410",
"original": "/system/pictures/pictures/000/000/095/original/greylag_goose.jpg?1464088410"
}
}The Users suggest service supports efficient search for users. Can be used to provide autocomplete functionality when searching for users.
GET /users/suggest
| Parameter | Description |
|---|---|
| text | the text to use to search for users |
The service will returns JSON with the user's displayname (or email if displayname is not set) and id:
[["[email protected]", 4], ["Bjørn", 1]]The search service searches for the user by searching the displayname, firstname, lastname and email of the user.
GET /users/search
| Parameter | Description |
|---|---|
| term | the text to use to search for users |
The service will returns JSON in this format (with search term "bj"):
[
{
"_index": "users",
"_type": "user",
"_id": "1",
"_score": 0.20952989,
"_source": {
"firstname": "Bjørn",
"displayname": "Bjørn",
"id": 1,
"email": "[email protected]",
"lastname": "Hjelle"
},
"highlight": {
"firstname": [
"<span class=\"highlight\">Bj</span>ørn"
],
"displayname": [
"<span class=\"highlight\">Bj</span>ørn"
],
"email": [
"<span class=\"highlight\">bj</span>[email protected]"
]
}
},
{
"_index": "users",
"_type": "user",
"_id": "4",
"_score": 0.17371339,
"_source": {
"firstname": null,
"displayname": null,
"id": 4,
"email": "[email protected]",
"lastname": null
},
"highlight": {
"email": [
"<span class=\"highlight\">bj</span>[email protected]"
]
}
}
]Use this service to follow another user. is the id of the user that the logged in user will follow:
POST /users/<id>/follow
Use this service to stop following a user. is the id of the user that the logged in user will stop follow:
POST /users/<id>/unfollow
Use this service to list the users that a user is following:
GET /users/<id>/following
Will return a JSON-array (with only one element in this example) :
[
{
"id": 4,
"email": "[email protected]",
"firstname": null,
"lastname": null,
"displayname": null
}
]Use this service to list the users that follows a user:
GET /users/<id>/followers
Will return a JSON-array (with only one element in this example):
[
{
"id": 1,
"email": "[email protected]",
"firstname": "Bjørn",
"lastname": "Hjelle",
"displayname": "Bjørn"
}
]Use this service to add a profile picture to the logged in user.
POST /user/picture
| Parameter | Description |
|---|---|
| picture[content_type] | Content type of the picture, e g "image/jpg" |
| picture[headers] | |
| picture[tempfile] | |
| primary | Set to "true" if this should be the 'primary' picture. Default is false. Users for now have only one picture so this parameter has no effect. |
The tags suggest service supports efficient search for used tags, so that you can present users with tags used by others:
GET /tags/suggest
| Parameter | Description |
|---|---|
| text | the text to use to search for tags |
The service will return JSON on this format (an array of strings beginning with the search term):
["bioblitzmai2015", "bjorn"]Collections are like views on the taxonomy that can be created for different purposes and used to filter the content returned from the taxa search service.
GET /collections
Returns available collections.
| Parameter | Description |
|---|---|
| collection_id | Get collections that have the collection as a parent |
Services to get and set settings for the user.
In the settings you can set parameters that limit the data returned from the other services. However, if set as a parameter when calling a service, that parameter will override the value in the settings.
GET /settings
Returns the user's settings.
PUT /settings
| Parameter | Description |
|---|---|
| collection_id | A collection to use as a filter for taxa search |
| languages | A comma seperated list of ISO 639-2 language codes, e g, "nob, nno, eng" |
| region | A region to use as a filter for taxa search |
| tag_list | A string with tags, separated with spaces |
The parameters must be supplied as the content of the HTTP PUT in a JSON hash with key "settings". See example program for details (update_settings.rb)
Services to get names and slugs (unique codes) of languages.
GET /languages
Returns the languages that are in use in Biocaching, as JSON in this format:
[
{
"id": 1,
"slug": "eng",
"name": "Engelsk"
},
{
"id": 4,
"slug": "nob",
"name": "Norsk bokmål"
},
{
"id": 11,
"slug": "non",
"name": "Norsk nynorsk"
},
{
"id": 10,
"slug": "ces",
"name": "Tsjekkisk"
}
]| Parameter | Description |
|---|---|
| language_iso | Get the names of the languages in a specific language. Default is "eng" |
Services to get names and slugs (unique codes) of regions.
GET /regions
Returns the regions that are in use in Biocaching, as JSON in this format:
[
{
"id": 1,
"slug": "nor",
"name": "Norge"
},
{
"id": 2,
"slug": "ces",
"name": "Tsjekkia"
}
]| Parameter | Description |
|---|---|
| language_iso | Get the names of the regions in a specific language. Default is "eng" |
Services to handle terms of use.
Returns the current version of the terms of use.
GET /admin/terms
Returns the terms for using the API and the Biocaching services. This service returns json on this format:
{
"terms": [
"term nr 1",
"term nr 2",
"term nr 3"
],
"updated_at": "2016-04-13 10:57:00"
}Returns whether or not the user has accepted the current terms of use.
GET /admin/terms/status
This service returns json on this format if the user has accepted the terms:
{
"status": "accepted"
}If the user has not accepted the terms, this is returned:
{
"status": "not accepted"
}Returns the current version of the terms of use.
GET /admin/terms
Returns the terms for using the API and the Biocaching services. This service returns json on this format:
{
"terms": [
"term nr 1",
"term nr 2",
"term nr 3"
],
"updated_at": "2016-04-13 10:57:00"
}| Parameter | Description |
|---|---|
| language_iso | Get the terms of use in a specific language. Default is "eng" |
Accepts the terms for the user that has logged in.
POST /admin/terms/accept
The service will return json to indicate that the terms was successfully accepted:
{
"status": "accepted"
}