Get location data
GET/projects/{projectId}/entities/{entityId}/location/data
Base URL: https://api.tinkermode.com
Get the location data.
Use the begin and end parameters to fetch entries by time range.
But if the latest parameter is true, the begin and end parameters
will be ignored, and the latest location will be returned.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a user API key of a user with permission to read the entity location, a service account token with the same permission, or a project API key.
Path parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
projectId | integer | Yes | The unique ID for a specified project. | |
entityId | string | Yes | Entity ID (unique within project) |
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
areaIds | string | No | If set, return only location records with matching area IDs. The value should be comma-separated list. | |
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. | |
end | string | No | The end time of the data entries. The format follows RFC3339. | |
floorId | integer | No | If set, return only location records with matching floor ID. | |
includeDescendants | boolean | No | Set this to true to include descendant entities' location. The default is false. | |
latest | boolean | No | Set this to true to obtain the latest location. The default is false. | |
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.
You can also specify the special value self to use the geometry of the entity specified
by entityId as the point. This is useful for querying entities located at a specific
entity's position. The entity must have a Point geometry type.
| |
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 3-dimensional real numbers. 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.
You can also specify the special value self to use the geometry of the entity specified
by entityId as the polygon. This is useful for querying entities within a geofence area
(e.g., "Which entities are currently in Area A?"). The entity must have a Polygon geometry type.
| |
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. | |
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 location 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.
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. |
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 The requested data does not exist or is not accessible.
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. |