Get GeoJSON formatted geospatial data
GET/homes/{homeId}/smartModules/{moduleId}/collections/{collectionId}/data
Base URL: https://api.tinkermode.com
Get GeoJSON formatted geospatial data specified by collection ID. Use comma-separated
searchKeys string in query parameters to fetch multiple records representing object
locations. Use the begin and end parameters to fetch entries by time range. Use the ts
parameters to fetch one entry before a point in time. Use the latest parameter to fetch the
latest record without any specified time. The areaIds, floorId, and attributeQuery
parameters are optional filters that ca be used in conjunction with the time range query
parameters to fetch records with specific values.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a user, service account, or project API key.
Path parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
homeId | integer | Yes | The unique ID for a home. | |
moduleId | string | Yes | The unique ID for a smart module. | |
collectionId | string | Yes | Collection ID. It must be unique per home. |
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
areaIds | string | No | Specify area IDs to search objects only in the specified areas from the GeoTSDB storage.
The areaIds parameter allows multiple values, separated by commas (",").
| |
attributeQuery | string | No | A filter string starting with a conjunction. Supported conjunctions are AND()
and OR(). A conjunction takes a comma-separated condition string like AND (group==="group_1",maxSpeed<5). Each condition string defines a filter for the
attribute value. The left-hand side must be a valid attribute field name. The
right-hand side must be a value condition. For example, group==="group_1" matches
any records where the group attribute value exactly matches "group_1".
Supported operators are following
| Operator | |
| --- | --- |
| === | exact match |
| == | substring match |
| ~== | included in array as exact match. name~==["john"|"jeff"|"jack"] matches one of the three. |
| ~= | included in array as substring match. name~=["j"|"e"] matches "john", "jeff", "jack", and "ethan". |
| < | less than |
| <= | less than or equal to |
| > | greater than |
| >= | greater than or equal to |
This parameter is only supported when the latest is true in the query.
| |
begin | string | No | The beginning time of the data entries. The format follows RFC3339. It's required when the latest is false and ts is not specified. | |
end | string | No | The end time of the data entries. The format follows RFC3339. It's required when the latest is false and ts is not specified. | |
floorId | integer | No | Specify floor ID to search objects in the specified floor ID from the GeoTSDB. | |
geometrySearchKey | string | No | Specify a search key to resolve the geometry (point or polygon) from the latest stored data
for that search key. This enables self-reference spatial queries where an object's own geometry
is used as the query filter. For example, setting geometrySearchKey to an entity's search key
will use that entity's current location (point) or area (polygon) to find other objects that
intersect with it. The geometry type is automatically determined from the stored data.
This parameter is mutually exclusive with point and polygon. Specifying both will result in an error.
This parameter is only supported when the latest is true in the query.
| |
latest | boolean | No | The flag to fetch the latest data entry. | |
point | string | No | Specify this query parameter enabling to select location data whose geometry data intersects
with a specified point. The format of the point is array of real numbers of longitude and
latitude [longitude,latitude] e.g. [139.78186023120884, 35.689037335151994]. The geodetic of longitude and latitude must be in WGS84.
This parameter is only supported when the latest is true in the query.
| |
polygon | string | No | Specify this query parameter enabling to select location data whose geometry data intersects
with a specified polygon. The format of the polygon is the same as GeoJSON's coordinates. The longitude and latitude values in an array must be longitude first and
the each last array is separated by comma e.g. [[[longitude,latitude],[longitude,latitude],[longitude,latitude]]]
This parameter is only supported when the latest is true in the query.
| |
samplingFactor | integer | No | Specify sampling factor to search objects in the specified sampling interval. When samplingFactor is 2, the data is sampled at 2 second interval. The sampling factor is only effective when the begin and end are specified.
| |
searchKeyPrefixes | string | No | When searchKeyPrefixes is specified, all the geospatial data whose searchKeys is prefixed by this parameters will be returned. For example, if you specify searchKeyPrefixes as "foo::,bar::", data with searchKey such as "foo::1" and "bar::2" will be returned. Note that you can specify either the searchKeyPrefixes parameter or the searchKeys parameter. | |
searchKeys | string | Yes | Specify keywords to search specific objects in the GeoTSDB storage. The searchKeys
parameter allows multiple values, separated by commas (","). For example, if you
specify the searchKeys as "building::st_ave,worker::john_smith", objects with
searchKey such as "building::st_ave" and "worker::john_smith" will be returned.
| |
selectAttributes | string | No | Specify keywords to project specific attributes in the geo-object. The selectAttributes parameter allows multiple values, separated by commas (",").
| |
ts | string | No | The point in time (in RFC3339) to fetch data entries from. This value can not be specified with begin and end. |
Responses
200 The requested geospatial data entries are returned.
Content type: application/json
| Property | Type | Required | Constraints | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
begin | string | No | read-only (server-generated) | The begin time of data entries. The format follows RFC3339. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
collectionId | string | No | read-only (server-generated) | Identifier of the GeoTSDB collection. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
data | array<object> | No | read-only (server-generated) | Geospatial Time-series data. Each entry contains the timestamp of the value in RFC3339 format and GeoJSON formatted location data. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
end | string | No | read-only (server-generated) | The end time of data entries. The format follows RFC3339. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Response example
{
"begin": "2023-03-25T09:00:00+09:00",
"collectionId": "tokyo",
"data": [
{
"areas": [
{
"areaId": "tyo_office"
}
],
"attributes": {
"place_in": "2023-03-25T00:00:00.010Z",
"placeId": "tyo_office"
},
"floorId": 1234,
"geometry": {
"coordinates": [
139.78204030637045,
35.68893985910911
],
"type": "Point"
},
"searchKey": "worker::user-1",
"timestamp": "2023-03-25T09:00:00.01+09:00"
},
{
"floorId": 1234,
"geometry": {
"features": [
{
"geometry": {
"coordinates": [
[
[
139.78186023120884,
35.689037335151994
],
[
139.78207804723996,
35.688811329363205
],
[
139.78216797128977,
35.68887056972147
],
[
139.78194865652313,
35.689095763833905
],
[
139.78186023120884,
35.689037335151994
]
]
],
"type": "Polygon"
},
"properties": {},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"searchKey": "site::tyo_office",
"timestamp": "2023-03-25T09:00:00+09:00"
}
],
"end": "2023-03-25T09:00:00.01+09:00"
}401 Authorization is required to access this resource.
403 Request failed because of denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
404 Any requested geospatial data entries are not found.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
429 Request failed because of rate limit.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |