Skip to content

Observations Web Service

Jump to bottom
Abdullah Almsaeed edited this page Jun 19, 2019 · 14 revisions

Table of Contents

Introduction

The TreeSnap observations web service API provides the user with privileged access to observations. When authenticated, accurate location information along with private information such as your own private comments become available. The response returned by all of TreeSnap web services are formatted as JSON.

My Observations API

Get all observations that belong to the currently authenticated user. To learn how to authenticate a user, please read our documentation on how to authenticate using OAuth personal tokens.

URL: https://treesnap.org/web-services/v1/my-observations

Method: GET

Request Parameters

Parameter Type Default Description
page Integer 1 Optional. Page number
per_page Integer 25 Optional. Number of results per page.
filters JSON null Optional. A JSON object describing a set of filtering criteria. Please see the filters section for more info.

Observations API

Get all observations despite who owns the observation. Private observations will not be included in the response unless the authenticated user has the privileges necessary to view them. Observations that are not owned by the current user may contain fuzzified location data. If so, the location_accuracy parameter in the response will read "Within 8 Kilometers Radius" as opposed to "Within Float Meters Radius"

URL: https://treesnap.org/web-services/v1/observations

Method: GET

Request Parameters

Parameter Type Default Description
page Integer 1 Optional. Page number. Minimum: 1.
per_page Integer 25 Optional. Number of results per page. Maximum: 100. Minimum: 1.
filters JSON null Optional. A JSON object describing a set of filtering criteria. Please see the filters section for more info.

Response

The JSON response from the server will be structured in the following way for both API end-points (/my-observations and /observations). The data types listed below are JSON data types

{
	"error_code": "Number",
	"data": {
		"current_page": "Number",
		"first_page_url": "String",
		"from": "Number",
		"last_page": "String",
		"last_page_url": "String",
		"next_page_url": "String",
		"path": "String",
		"per_page": "Number",
		"prev_page_url": "String",
		"to": "Number",
		"total": "Number",
                "data": [
                {
                  "id": "Number",
                  "custom_id": "String",
                  "category": "String",
                  "genus": "String",
                  "species": "String",
                  "submitter": "String",
                  "thumbnail": "String",
                  "images": "Object",
                  "longitude": "Number",
                  "latitude": "Number",
                  "location_accuracy": "String",
                  "collection_date": "String format: Year-Month-Day Hours:Minutes:Seconds GMT Timezone Difference (e.g, +0200)",
                  "meta_data": "Object",
                  "url": "String"
                }
              ]
    }
}

Accessing Individual Observations

To access an individual observation, you must already know the primary ID of the observation.

URL: https://treesnap.org/web-services/v1/observation/{ID}

Method: GET

Replace {ID} with the observation's id which is always an integer.

Example Response

[
  "data" => [
    "id" => 1026
    "custom_id" => "5d0a4a7d04e26"
    "category" => "American Elm"
    "genus" => "Unknown"
    "species" => "Unknown"
    "submitter" => "Dr. Viola Weimann"
    "thumbnail" => "http://localhost/storage/thumbnails/autumn.jpg"
    "images" => [
      "images" => [
        0 => "http://localhost/storage/images/flower.jpg"
      ]
    ]
    "longitude" => 156.61788
    "latitude" => -39.893909
    "location_accuracy" => "Within 52.46 meters radius"
    "collection_date" => "2019-06-19 14:45:17 GMT +0000"
    "meta_data" => [
      "comment" => "Comment on record 2687"
      "heightNumeric" => 2919
      "diameterNumeric" => 973
      "heightFirstBranch" => 1946
      "heightNumeric_units" => "Feet"
      "heightNumeric_values" => [
        "US_unit" => "Feet"
        "US_value" => 2919
        "metric_unit" => "Meters"
        "metric_value" => 889.7112
      ]
      "diameterNumeric_units" => "Inches"
      "diameterNumeric_values" => [
        "US_unit" => "Inches"
        "US_value" => 973
        "metric_unit" => "cm"
        "metric_value" => 2471.42
      ]
      "heightFirstBranch_units" => "Feet"
      "heightFirstBranch_values" => [
        "US_unit" => "Feet"
        "US_value" => 1946
        "metric_unit" => "Meters"
        "metric_value" => 593.1408
      ]
    ]
    "url" => "http://localhost/observation/1026"
  ]
  "error_code" => 0
]

Filters

By specifying the filters parameter, you can provide a JSON string to search and filter through observations.

Example Filter

The following curl command retrieves all observations submitted within the period of April 21, 2018 until April 21 2019.

curl -X GET \
  'https://treesnap.org/web-services/v1/observations?per_page=10&page=1&filters=\{"date_start":"21/04/2018","date_end":"21/04/2019"\}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-API-TOKEN'

Request Examples

Examples of sending a request to the observations web service.

CURL

curl -X GET \
  'https://treesnap.org/web-services/v1/observations?per_page=10&page=2' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-API-TOKEN'

Python using requests

import requests

url = "https://treesnap.org/web-services/v1/observations"

querystring = {"per_page":"10","page":"2"}

headers = {
    'Accept': "application/json",
    'Authorization': "Bearer YOUR-API-TOKEN",
}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)

PHP with Guzzle

<?php
$accessToken = 'YOUR-API-TOKEN';
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://treesnap.org/web-services/v1/my-observations', [
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer '.$accessToken,
    ],
]);

Response Example

{
    "data": {
        "current_page": 2,
        "data": [
            {
                "id": 3,
                "custom_id": null,
                "category": "Other (Other)",
                "genus": "Unknown",
                "species": "Unknown",
                "submitter": "Abdullah Almsaeed",
                "thumbnail": "https://treesnap.org/storage/thumbnails/RayTr5919eb535944f.jpeg",
                "images": {
                    "images": [
                        "https://treesnap.org/storage/images/RayTr5919eb535944f.jpeg",
                        "https://treesnap.org/storage/images/DM3kh5919eb535afe8.jpeg"
                    ]
                },
                "longitude": -83.94062614076206,
                "latitude": 35.94815787862609,
                "location_accuracy": "Within 10 meters radius",
                "collection_date": "2017-05-15 13:54:13 GMT +0000",
                "meta_data": {
                    "otherLabel": "Other",
                    "diameterNumeric": 25,
                    "diameterNumeric_units": "Inches",
                    "diameterNumeric_values": {
                        "US_unit": "Inches",
                        "US_value": 25,
                        "metric_unit": "cm",
                        "metric_value": 63.5
                    }
                },
                "url": "https://treesnap.org/observation/3"
            },
            {
                "id": 4,
                "custom_id": null,
                "category": "Other (Other)",
                "genus": "Unknown",
                "species": "Unknown",
                "submitter": "Abdullah Almsaeed",
                "thumbnail": "https://treesnap.org/storage/thumbnails/hI5o559368ce080f2b.jpeg",
                "images": {
                    "images": [
                        "https://treesnap.org/storage/images/hI5o559368ce080f2b.jpeg",
                        "https://treesnap.org/storage/images/kOneA59368ce083ca6.jpeg",
                        "https://treesnap.org/storage/images/HFG6859368ce085b87.jpeg"
                    ]
                },
                "longitude": -83.94200689167151,
                "latitude": 35.94777637630324,
                "location_accuracy": "Within 10 meters radius",
                "collection_date": "2017-05-16 08:39:06 GMT +0000",
                "meta_data": {
                    "otherLabel": "Other",
                    "diameterNumeric": 50,
                    "diameterNumeric_units": "Inches",
                    "diameterNumeric_values": {
                        "US_unit": "Inches",
                        "US_value": 50,
                        "metric_unit": "cm",
                        "metric_value": 127
                    }
                },
                "url": "https://treesnap.org/observation/4"
            }
        ],
        "first_page_url": "https://treesnap.org/web-services/v1/my-observations?page=1",
        "from": 3,
        "last_page": 6,
        "last_page_url": "https://treesnap.org/web-services/v1/my-observations?page=6",
        "next_page_url": "https://treesnap.org/web-services/v1/my-observations?page=3",
        "path": "https://treesnap.org/web-services/v1/my-observations",
        "per_page": "2",
        "prev_page_url": "https://treesnap.org/web-services/v1/my-observations?page=1",
        "to": 4,
        "total": 11
    },
    "error_code": 0
}

Meta Data Labels

The following is human readable mapping for the meta data keys that show up in the meta: {} field of an observation.

return [
            'ashSpecies' => 'Species',
            'seedsBinary' => 'Seeds',
            'flowersBinary' => 'Flowers',
            'emeraldAshBorer' => 'Ash Borer',
            'woollyAdesCoverage' => 'Woolly Adelgids',
            'chestnutBlightSigns' => 'Chestnut Blight',
            'acorns' => 'Acorns',
            'cones' => 'Cones',
            'heightFirstBranch' => 'Height of First Branch',
            'oakHealthProblems' => 'Health Problems',
            'diameterNumeric' => 'Tree Diameter',
            'crownHealth' => 'Crown Health',
            'crownClassification' => 'Crown Classification',
            'otherLabel' => 'Tree Type',
            'locationCharacteristics' => 'Habitat',
            'nearbyTrees' => 'Trees Nearby',
            'nearByHemlock' => 'Nearby Hemlocks',
            'treated' => 'Treated',
            'partOfStudy' => 'Study',
            'heightNumeric' => 'Tree Height',
            'burrs' => 'Nuts/burrs',
            'catkins' => 'Catkins',
            'comment' => 'Comment',
            'diameterNumeric_confidence' => 'Diameter Confidence',
            'heightFirstBranch_confidence' => 'Height of First Branch Confidence',
            'numberRootSprouts' => 'Number of Root Sprouts',
            'numberRootSprouts_confidence' => 'Number of Root Sprouts Confidence',
            'heightNumeric_confidence' => 'Tree Height Confidence',
            'torreyaFungalBlight' => 'Fungal Blight',
            'conesMaleFemale' => 'Cones',
            'deerRub' => 'Deer Rub',
            'madroneDisease' => 'Disease',
            'crownAssessment' => 'Tree Crown Assessment',
            'standDiversity' => 'Stand Diversity'
];
Clone this wiki locally