API Spec
GET
/v1/get-landscape
Setup
To setup the API on your GCP project, please follow the detailed GCP documentation here
Request GetLandscape returns a list of landscape features in GeoJSON format contained in Level 13 S2 Cell corresponding to the region of interest in the request. Each feature has geometry, id and type properties (see the response details below).
There are two options to specify a S2Cell in this API
Option 1: Specify by a S2Cell ID (level 13) directly.
Request S2cell ID
Response: Landscape feature (red)
Option 2: Specify by a coordinate point (latitude and longitude)
Request Altitude and longitude
S2Cell ID of the request coordinate
Response: Landscape feature (red)
Option 1: Specify by a S2Cell ID (level 13) directly.
Request S2cell ID
Response: Landscape feature (red)
Option 2: Specify by a coordinate point (latitude and longitude)
Request Altitude and longitude
S2Cell ID of the request coordinate
Response: Landscape feature (red)
Request
Description: Specify either a Level 13 S2cell ID or a coordinate point (not both)
| Parameter | Required | Type | Description |
|---|---|---|---|
Option 1: Specify a level 13 S2Cell ID |
|||
s2cell |
Required | uint64 | Level 13 S2 cell ID (Decimal) e.g. 4316826463333515264 |
Option 2: Specify a coordinate point (this coordinate will be converted into a Level 13 S2 Cell ID automatically) |
|||
lat |
Required | float64 | Latitude e.g. 18.624 |
lng |
Required | float64 | Longitude e.g. 73.076 |
| Common parameters | |||
apikey |
Required | string | API Key e.g. PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk This can be generated by Apigee on a customer GCP project. |
include_non_agricultural_areas |
Optional | bool | If true, areas with non-agricultural features, like deserts, hills and cities, are included in the output. The default is false. |
data_version |
Optional |
uint64 |
Specifies the version of the data. e.g. 2 If not specified, the latest version of the data will be returned. |
Request Example 1 (look up by a S2cell ID):
Unset
/v1/get-landscape?s2cell=4316826463333515264&apikey=PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk
Request Example 2 (look up by lat-lng):
Unset
/v1/get-landscape?lat=18.624&lng=73.076&apikey=PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk
Response
Description: Dataset version and a list of features in GeoJSON format
Content-Type: application/json
Status codes:
Code |
Description |
|---|---|
200 OK |
The request succeeded, The requested data has been fetched and transmitted in the message body. |
204 No Content |
There is no data to send back for this request, This means there is no landscape feature in a requested S2 cell. |
400 Bad Request |
The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax) |
401 Unauthorized |
This error arises when the expected API key does not exist or invalid. |
422 Unprocessable Entity |
The server cannot process the request due to invalid or incorrect input data. |
Properties of each feature:
Feature Property |
Type |
Description |
|---|---|---|
id |
string |
A feature ID, represented by the plus code of the centroid of the feature. https://plus.codes |
properties.alu_type |
enum |
Represents the type of feature.
|
properties.area_sq_m |
float64 |
Represents the area of feature in square meters. |
properties.class_confidence |
float64 |
Represents the confidence in the accuracy of the classification. |
properties.capture_timestamp_usec |
unit64 |
Represents the capture timestamp in microseconds for the observation’s source image. |
Response Body Examples (formatted):
Status: 200 OK
Unset
{
"data_version": 2,
"geojson": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "7JCMJ3FG+RP55",
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[73.0768021, 18.624176199999997],
[73.07682989999999, 18.6242307],
[73.0768585, 18.6242129],
[73.0768587, 18.6241949],
[73.0768872, 18.624195099999998],
[73.076915, 18.6242496],
[73.0770005, 18.624232400000004],
[73.07702859999999, 18.624259800000004],
[73.0771992, 18.624252500000004],
[73.0771984, 18.6243248],
[73.077033, 18.624711599999998],
[73.07703180000001, 18.62482],
[73.07689909999999, 18.624818599999998],
[73.0768239, 18.624763599999998],
[73.0767195, 18.624780599999998],
[73.07654, 18.624733600000003],
[73.0765598, 18.624652499999996],
[73.0766468, 18.6244998],
[73.0767165, 18.624202399999998],
[73.0767455, 18.624157600000004],
[73.0768021, 18.624176199999997]
]
]
]
},
"properties": {
"alu_type": "field",
"area_sq_m": 3205.272175774053,
"class_confidence": 0.74501633644104,
"capture_timestamp_usec": 1648684800000000
}
},
....
]
}
}
Status: 422 Unprocessable Entity
Invalid type of s2cell.
Unset
{
"detail": [
{
"type": "int_parsing",
"loc": [
"query",
"s2cell"
],
"msg": "Input should be a valid integer, unable to parse string as an integer",
"input": "\"\"",
"url": "https://errors.pydantic.dev/2.6/v/int_parsing"
}
]
}
Invalid type of lat and lng.
Unset
{
"detail": [
{
"type": "float_parsing",
"loc": [
"query",
"lat"
],
"msg": "Input should be a valid number, unable to parse string as a number",
"input": "\"\"",
"url": "https://errors.pydantic.dev/2.6/v/float_parsing"
},
{
"type": "float_parsing",
"loc": [
"query",
"lng"
],
"msg": "Input should be a valid number, unable to parse string as a number",
"input": "\"\"",
"url": "https://errors.pydantic.dev/2.6/v/float_parsing"
}
]
}