(Quick Reference)

Observations

list

  • Path : /api/observation
  • Parameters :
    • sGroup : speciesGroupId. default all
    • habitat : habitat id. default all
    • user : observation author id
    • type : nearBy|...
    • lat : latitude value in decimal
    • long: longitude value in float
    • daterangepicker_start , daterangepicker_end
    • bounds : swLat, swLong, neLat, neLon
    • isFlagged : true| false. default false
    • featureBy : true|false. default false
    • isChecklistOnly : true| false. default false
    • tag : tag name
    • webaddress : to filter observations with group with this webaddress
    • speciesName:'Unknown' to get all unidentified observations
    • max: limit of number of results. default 24
    • offset : offset in to the result set. default 0
    • sort: lastRevised|createsOn|visitCount. default lastRevised desc, id asc
  • REST method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json
  • Requests :
    • _NearBy Observations_

http://indiabiodiversity.saturn.strandls.com/api/observation?type=nearBy&lat=10&long=76&maxRadius=1000
    • _My collection_

http://indiabiodiversity.saturn.strandls.com/api/observation?user=4440
    • _Within certain bounds_

http://indiabiodiversity.org/api/observation?bounds=4.8282597468669755%2C69.521484375%2C37.09023980307208%2C95.888671875&max=24&offset=0
    • _With species group and habitat filter_

http://indiabiodiversity.org/api/observation?bounds=4.8282597468669755,69.521484375,37.09023980307208,95.888671875&max=24&offset=0&sGroup=837&habitat=267835
  • Response :

{
    "success": true,
        "status": 200,
        "msg": "",
        "model": {
            "observationInstanceList": [ … ]
                "checklistCount": 27,
            "observationCount": 20,
            "speciesGroupCountList": [],
            "queryParams": {
                "isDeleted": false,
                "max": 24,
                "offset": 0
            },
            "activeFilters": {
                "append": true
            },
            "resultType": "observation",
            "geoPrivacyAdjust": 0.208835,
            "canPullResource": true
        }
}

related

  • Path : /api/related/observation/$filterProperty/$filterPropertyValue
  • Parameters :
    • filterProperty : speciesName | speciesGroup | featureBy | user | nearBy | nearByRelated | taxonConcept | latestUpdatedObservations
    • filterPropertyValue : obvId | speciesGroupId | - | userId | lat,lng | obvId |taxonConceptId | userGroupWebaddress, sort
    • limit : max number of records. default 12
    • offset : offset into the result set. default 0
  • REST method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json
  • Requests :
    • Featured Observations__

http://indiabiodiversity.org/api/related/observation/featureBy?limit=10&offset=0
    • _Related Observations by species name_

http://indiabiodiversity.org/api/related/observation/speciesName/358907
    • _Related Observations by location_

http://indiabiodiversity.org/api/related/observation/nearByRelated/358907

occurrences

http://indiabiodiversity.org/api/observation/occurrences?sGroup=829&habitat=267835&offset=0&max=-1&fl=id&fetchField=id,latitude,longitude,isChecklist,geoPrivacy

All unique species available in the list of observations satisfying certain criteria

http://indiabiodiversity.org/api/observation/distinctReco?sGroup=829&habitat=267835&offset=0&fl=id&bounds=4.8282597468669755%2C69.521484375%2C37.09023980307208%2C95.888671875

Count of observations as per speciesGroup

http://indiabiodiversity.org/api/observation/speciesGroupCount

show

  • Path : /api/observation/id
  • Parameters : id long format
  • REST method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json
  • Request :

http://indiabiodiversity.org/api/observation/269204
  • Response :
    • Successful response

{
    "success": true,
        "status": 200,
        "msg": "",
        "instance": {
            "id": 245,
            "placeName": "Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India",
            "reverseGeocodedName": "Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India",
            "geoPrivacy": false,
            "locationAccuracy": "Approximate",
            "topology": "POINT (76.42376839999997 9.6297152)",
            "group": {
                "id": 6,
                "name": "Birds",
                "groupOrder": 0
            },
            "habitat": {
                "id": 2,
                "name": "Forest",
                "habitatOrder": 2
            },
            "fromDate": "2014-05-31T18:30:00Z",
            "toDate": "2014-05-31T18:30:00Z",
            "createdOn": "2014-06-04T06:55:21Z",
            "lastRevised": "2014-06-05T02:51:53Z",
            "author": {
                "id": 2,
                "name": "Sravanthi Mutyala",
                "email": "pearlsravanthi@gmail.com",
                "icon": "http://localhost/biodiv/users//b4b3727c-b589-4953-bea4-76e7b24d8d26/resources/983_th1.jpg"
            },
            "notes": "    Found this bird on my trip tonbsp;Kumarakom Bird Sanctuary</p>",
            "summary": "Observed by <b><a href='/user/show/2'>Sravanthi Mutyala</a></b> at <b>'Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India'</b> on <b>June 01, 2014</b>.",
            "rating": 0,
            "maxVotedReco": {
                "name": "Parakeet",
                "taxonomyDefinition": null
            },
            "resource": [
            {
                "id": 1,
                "url": "http://www.youtube.com/watch?v=v8HVWDrGr6o",
                "icon": "http://img.youtube.com/vi/v8HVWDrGr6o/default.jpg",
                "uploader": {
                    "id": 2,
                    "name": "Sravanthi Mutyala",
                    "email": "pearlsravanthi@gmail.com",
                    "icon": "http://localhost/biodiv/users//b4b3727c-b589-4953-bea4-76e7b24d8d26/resources/983_th1.jpg"
                },
                "type": "Video",
                "uploadTime": "2014-06-04T06:55:22Z",
                "rating": 2
            }
            ],
                "recommendationVote": [
                {
                    "recommendation": {
                        "name": "Parakeet",
                        "taxonomyDefinition": null
                    },
                    "commonNameReco": null,
                    "author": {
                        "id": 2,
                        "name": "Sravanthi Mutyala",
                        "email": "pearlsravanthi@gmail.com",
                        "icon": "http://localhost/biodiv/users//b4b3727c-b589-4953-bea4-76e7b24d8d26/resources/983_th1.jpg"
                    },
                    "confidence": "I am certain",
                    "votedOn": "2014-06-05T02:27:28Z",
                    "comment": null
                }
            ],
                "userGroups": [
                {
                    "id": 3,
                    "name": "The Western Ghats",
                    "description": "<h2 style="margin: 10px 0px; font-family: Verdana, Helvetica, sans-serif; font-weight: normal; line-height: 40px; color: rgb(85, 85, 85); text-rendering: optimizelegibility; font-size: 31.5px; padding: 5px; border-bottom-width: 1px; border-bottom-style: solid; border-bottom-color: rgb(229, 229, 229);">rnt<span style="color: rgb(94, 94, 94); font-size: 14px;">The Western Ghats, a mountainous ridge running parallel to the west coast of India&rsquo;s ancient peninsula, has a rich and intriguing history.&nbsp;</span><span style="color: rgb(94, 94, 94); font-size: 14px;">The Western Ghat portal seeks to provide a platform for aggregating diverse information on the biodiversity of the Western Ghats. As interested, discerning readers, students and researchers we request you to participate and create an online open collaborative system for sharing biodiversity information.</span></h2>rn<p>rnt&nbsp;</p>rn",
                    "domainName": "http://thewesternghats.indiabiodiversity.org",
                    "webaddress": "the_western_ghats",
                    "foundedOn": "2013-07-15T18:09:55Z",
                    "icon": "/7d3bb3f5-2626-4a13-b9aa-ecfaabe84263/resources/807.gif"
                }
            ],
                "annotations": [],
                "isDeleted": false,
                "isLocked": false,
                "isChecklist": false,
                "visitCount": 13,
                "flagCount": 0,
                "featureCount": 0
        }
}
    • in case of error

{
    "success": false,
        "status": 200,
        "msg": "Observation not found with id 2,755",
        "errors": []
}

save

  • Path : /api/observation/save
  • Parameters :
    • group : species group id
    • habitat : habitat id
    • notes : observation notes
    • fromDate : observed on date in format (dd/mm/yyyy)
    • placeName : String
    • locationAccuracy : Accurate|Approximate
    • geoPrivacy : true|false
    • agreeTerms : on|off
    • areas : WKT representation of topology of location. e.g., POINT(77.60492180000006 17.6740832)
    • resources : urls for the uploaded images and videos and their metadata as in following format
    • commonName: common name
    • languageName: language name
    • recoName: species scientific name
    • recoComment: comment
    • tags:tag1,tag2...
    • userGroupsList: csv of all user group id's
  • REST method : POST
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
  • Request :

http://indiabiodiversity.org/api/observation/save?url_1=http://www.youtube.com/watch?v=v8HVWDrGr6o&type_1=VIDEO&rating_1=2&resourceListType=ofObv&fromDate=01/06/2014&placeName=Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India&areas=POINT(76.42376839999997 9.6297152)&location_accuracy=Approximate&notes=    Found this bird on my trip to&nbsp;Kumarakom Bird Sanctuary</p>&tags=parrot, bird&agreeTerms=on&group_id=829&habitat_id=267838"
For example
file_1:v
url_1:http://www.youtube.com/watch?v=v8HVWDrGr6o
type_1:VIDEO
rating_1:3
resourceListType:ofObv
commonName:Parrot
languageName: English
recoName:Parakeet
recoComment: Please suggest exact scientific name
fromDate:01/06/2014
placeName:Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India
areas:POINT(76.42376839999997 9.6297152)
location_accuracy:Approximate
reverse_geocoded_name:
notes:<p>

Found this bird on my trip to&nbsp;Kumarakom Bird Sanctuary</p>

tags:bird tags:parrot userGroupsList:1 agreeTerms:on group_id:829 habitat_id:267838

  • Response :
    • Successful response :

{
    "success": true,
    "observationInstance": {
        "id": 345092,
        "placeName": "Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India",
        "reverseGeocodedName": "Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India",
        "geoPrivacy": false,
        "locationAccuracy": "Approximate",
        "topology": "POINT (76.42376839999997 9.6297152)",
        "group": {
            "id": 829,
            "name": "All",
            "groupOrder": 1
        },
        "habitat": {
            "id": 267838,
            "name": "Savanna",
            "habitatOrder": 4
        },
        "fromDate": "2014-05-31T18:30:00Z",
        "toDate": "2014-05-31T18:30:00Z",
        "createdOn": "2014-06-05T10:24:29Z",
        "lastRevised": "2014-06-05T10:24:30Z",
        "author": {
            "id": 1184,
            "name": "Sravanthi Mutyala",
            "email": "pearlsravanthi@gmail.com",
            "icon": "http://indiabiodiversity.saturn.strandls.com/biodiv/users//581308415/resources/581308415_th1.jpg"
        },
        "notes": "    Found this bird on my trip to",
        "summary": "Observed by <b><a href='/user/show/1184'>Sravanthi Mutyala</a></b> at <b>'Kumarakom Bird Sanctuary, SH 42, Kerala 686563, India'</b> on <b>June 01, 2014</b>.",
        "rating": 0,
        "maxVotedReco": null,
        "resource": [
        {
            "id": 277437,
            "url": "http://www.youtube.com/watch?v=v8HVWDrGr6o",
            "icon": "http://img.youtube.com/vi/v8HVWDrGr6o/default.jpg",
            "uploader": {
                "id": 1184,
                "name": "Sravanthi Mutyala",
                "email": "pearlsravanthi@gmail.com",
                "icon": "http://indiabiodiversity.saturn.strandls.com/biodiv/users//581308415/resources/581308415_th1.jpg"
            },
            "type": "Video",
            "uploadTime": "2014-06-05T10:24:29Z",
            "rating": 2
        }
        ],
            "recommendationVote": null,
            "userGroups": null,
            "annotations": null,
            "isDeleted": false,
            "isLocked": false,
            "isChecklist": false,
            "visitCount": 0,
            "flagCount": 0,
            "featureCount": 0
    }
}
    • in case of error :

{
    "success": false,
        "msg": "Failed to save observation",
        "errors": [
        {
            "field": "group",
            "message": "Property [group] of class [Observation] cannot be null"
        }
    ]
}

upload_resource

  • Path : /api/observation/upload_resource
  • Parameters :
    • resources : file attachment (MAX_IMAGE_SIZE = 104857600)
    • obvDir : directory into which the resource should be put into. If null, a new folder is created.
    • resType : species.participation.Observation | species.participation.Checklists | species.Species
  • REST method : POST
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
  • Request :

http://indiabiodiversity.org/api/observation/upload_resource?resType=species.participation.Observation
  • Response :
    • Successfull response

{
    "success": true,
        "status": 200,
        "msg": "",
        "model": {
            "observations": {
                "dir": "/7a4b7349-4845-468f-afba-a9986e9b2c93",
                "resources": [
                {
                    "fileName": "/7a4b7349-4845-468f-afba-a9986e9b2c93/704.JPG",
                    "url": "",
                    "thumbnail": "http://indiabiodiversity.org/biodiv/observations//7a4b7349-4845-468f-afba-a9986e9b2c93/704_gall.jpg",
                    "type": {
                        "enumType": "species.Resource$ResourceType",
                        "name": "IMAGE"
                    },
                    "jobId": 7661
                }
                ]
            }
        }
}
    • in case of error

{
    "success": false,
        "status": 500,
        "msg": "No file is attached",
        "errors": []
}

getRecommendationVotes

  • Path : /api/observation/id/getRecommendationVotes
  • Parameters :
    • max : number of recovotes to fetch. Default ordering is on number of votes for each name.
    • offset : offset of votes
  • REST Method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json
  • Request :

http://indiabiodiversity.org/api/observation/245/getRecommendationVotes
  • Response :
    • on success

{
    "success": true,
        "status": 200,
        "msg": "",
        "model": {
            "recoVotes": [
            {
                "recoId": 2693,
                "isScientificName": true,
                "name": "Test4",
                "authors": [
                {
                    "id": 2,
                    "name": "Sravanthi Mutyala",
                    "email": "pearlsravanthi@gmail.com",
                    "icon": "http://localhost/biodiv/users//b4b3727c-b589-4953-bea4-76e7b24d8d26/resources/983_th1.jpg"
                }
                ],
                    "votedOn": [
                        "2014-06-24T14:21:47Z"
                        ],
                    "noOfVotes": 1,
                    "totalVotes": 1,
                    "recoComments": [],
                    "obvId": 245,
                    "isLocked": false,
                    "commonNames": "",
                    "disAgree": true,
                    "showLock": true
            }
            ],
                "totalVotes": 1,
                "uniqueVotes": 1,
                "success": true
        }
}
    • on error

{
    "success": false,
        "status": 200,
        "msg": "Error while processing the request. Please report the necessary details to <span class='mailme'>support(at)indiabiodiversity(dot)org</span>",
        "errors": [
            "For input string: "268134ds""
            ]
}

addRecommendationVote

  • Path : /api/observation/id/getRecommendationVotes
  • Parameters :
    • obvId: observation id
    • recoName: scientific name
    • commonName: common name
    • languageName: language
    • recoComment: comment text
  • REST Method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
  • Request :

http://indiabiodiversity.org/api/observation/id/addRecommendationVote?obvId=245&recoName=Animalia&commonName=common name&languageName=English
  • Response :
    • on success

{
    "success": true,
        "status": 200,
        "msg": "Successfully added species name Animalia",
        "instance": {
            "id": 369875,
            "observation": 358907,
            "recommendation": {
                "id": 268187,
                "name": "Animalia",
                "taxonomyDefinition": {
                    "id": 872,
                    "name": "Animalia",
                    "canonicalForm": "Animalia",
                    "italicisedForm": "<i>Animalia</i>",
                    "rank": "Kingdom"
                }
            },
            "author": {
                "id": 1184,
                "name": "Sravanthi Mutyala",
                "icon": "http://graph.facebook.com/581308415/picture?type=large"
            },
            "confidence": "I am certain",
            "votedOn": "2015-01-22T15:34:37Z",
            "commonNameReco": {
                "id": 435387,
                "name": "Common Name",
                "language": {
                    "id": 205,
                    "name": "English"
                }
            }
        }
}
    • on error

{
    "status": 200,
    "success": "false",
    "msg": "No recommendation vote got added"
}

removeRecommendationVote

  • Path : /api/observation/id/removeRecommendationVote
  • Parameters :
    • recoId : recommendationId
  • REST Method : GET
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
  • Request :

  • Response :
    • on success

{
    "status": 200,
        "success": "true",
        "msg": "Successfully deleted species name Test indica"
}
    • on error

{
    "status": 200,
        "success": "false",
        "msg": "Recommendation not found with id 2701"
}

flagDelete

  • Path : /api/observation/id/flagDeleted
  • Parameters :
    • id : observation id
  • REST Method : DELETE or POST
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
  • Request :

http://indiabiodiversity.org/api/observation/flagDeleted?id=234
  • Response :
    • on success

{
    "success": true,
    "msg": "Observation 234 deleted",
    "errors": []
}
    • in case of error

{
    "success": false,
    "msg": "Observation 234sdf could not be deleted",
    "errors": [
    {
        "message": "For input string: "234sdf""
    }
    ]
}

{ "success": false, "msg": "Observation not found with id null", "errors": [] }

requestExport

  • Path : /api/observation/requestExport
  • Parameters :
    • filterUrl : filterUrl as in list call
    • downloadType
    • notes
    • source
    • REST Method : GET | POST
  • Headers Required : X-Auth-Token, Accept:application/json, text/json, X-AppKey
    • Permission : admin
    • Notes : the download will be scheduled and a link to download will be send to the requester email.
  • Request :