Skip to content

Observations Web Service

florence-77 edited this page Jan 31, 2025 · 1 revision

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 Filters

The following curl command retrieves all observations submitted within the period of April 15, 2024 until April 28, 2024. Note that if more observations than the per_page parameter are queried, the response is paginated. Adjust page and per_page to fetch the rest of the data.

curl -X GET \
  'https://treesnap.org/web-services/v1/observations?per_page=10&page=1&filters=\{"date_range":\{"start":"2024-04-15","end":"2024-04-28"\}\}' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR-API-TOKEN'

The below example filters by the same date range, but also only returns observations of the species Hemlock and American Chestnut. Note that categories must be an array, regardless of how many species one filters by. Also note that %20 must be used in place of the space in American Chestnut, to ensure a proper URL is formed.

curl -X GET \
  'https://treesnap.org/web-services/v1/observations?per_page=10&page=1&filters=\{"date_range":\{"start":"2024-04-15","end":"2024-04-28"\},"categories":\["Hemlock","American%20Chestnut"\]\}' \
  -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'
];