Return Places by Query
/mobile/platform/location/places/query
Call this operation to retrieve the places and, optionally, the associated devices that match the query properties that you specify in the request body.
Permissions
You can access this operation as a social user, a virtual user, an anonymous user, or a mobile user. If you access this operation as a mobile user, then you must be a member of the realm that's associated with the mobile backend.
Request
- application/json
object
Query Parameters
-
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
descendantDevices(optional):
boolean
Default Value:
false
Set to `true` to include in the response the `descendantDevices` property, which lists the devices that are associated with this place and all its child places. -
descendantsOf(optional):
number
Return places that are direct descendants of this place ID. When you use this query parameter, don't combine it with other parameters.
-
description(optional):
string
Filter results based on a case-insensitive partial match of this string with the place's description.
-
format(optional):
string
Default Value:
long
Allowed Values:[ "short", "long" ]
The response is in long format by default. Specify `short` to return only the `id`, `name`, `description`, `children`, and `label` properties. -
includeDescendantsInResult(optional):
string
Default Value:
all
Allowed Values:[ "all", "direct", "none" ]
How much of the place's hierarchy to include in the response.all
: (default) Include the specified place (root) and its children, grandchildren, and so on.direct
: Include just the root and its immediate children.none
: Include the root only.
-
inGeoFence(optional):
object gpsCircle
GPS circle.
-
label(optional):
string
Filter results based on a partial match of this string with the label.
-
limit(optional):
integer
Minimum Value:
0
Maximum Value:500
Default Value:40
Maximum number of items to return (between 0 and 500). If the requested limit is greater than `500`, then `500` is substituted. -
listOfPlaces(optional):
array listOfPlaces
Place ID(s) to search for. For example `[15,16]`.
-
name(optional):
string
Filter results based on a case-insensitive partial match of this string with the place's user-defined name.
-
nearestTo(optional):
object gpsPoint
GPS point.
-
offset(optional):
integer
Default Value:
0
Zero-based index of the first item to return. -
orderBy(optional):
string
Allowed Values:
[ "name", "label", "createdOn", "modifiedOn" ]
Field to order results by. Requires either `:asc` for ascending or `:desc` for descending. Example: `createdOn:asc`. -
search(optional):
string
Filter results based on a case-insensitive partial match of this string with either the place's name or description.
object
Attributes
object
-
latitude(optional):
number
Latitude of the center of the GPS circle.
-
longitude(optional):
number
Longitude of the center of the GPS circle.
-
radius(optional):
number
GPS circle's radius in meters.
array
object
-
latitude(optional):
number
GPS point's latitude
-
longitude(optional):
number
GPS point's longitude.
{
"limit":2,
"orderBy":"name:asc",
"format":"long",
"offset":0,
"inGeoFence":{
"gpsCircle":{
"longitude":122.262,
"radius":180000,
"latitude":37.4996
}
}
}
Response
- application/json
200 Response
object
Query Results
-
count(optional):
integer
Number of items in this response.
-
hasMore(optional):
boolean
`true` if there are more items to return.
-
items(optional):
array items
Minimum Number of Items:
1
Places found. -
limit(optional):
integer
Limit requested.
-
offset(optional):
integer
Offset (starting index) requested for this response.
-
totalResults(optional):
integer
Number of items that match the query.
array
1
-
Array of:
object Place
Title:
Place
The long format includes all properties. The short format contains only `id`, `name`, `description`, `children`, and `label`. The short format applies to `POST /mobile/platform/location/places` responses only.
object
Place
-
address(optional):
object Place's Address
Title:
Place's Address
GPS address of the place. -
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
children(optional):
array children
Minimum Number of Items:
0
Places that are the child places of this place. This includes the full hierarchy of places that descend from this place. -
createdBy:
string
User who added the place.
-
createdOn:
string
When the place was added.
-
descendantDevices(optional):
array descendantDevices
Minimum Number of Items:
0
Devices that are associated with this place and all its child places. This property is included in query results when the `descendantDevices` query parameter is set to `true`. All devices found are included in short form only. -
description:
string
Place's description.
-
devices(optional):
array devices
Minimum Number of Items:
0
Devices associated with this asset. Typically one device, but there can be multiple devices. -
hasChildren(optional):
boolean
Set to `true` if this place is a parent of other places.
-
id:
number
Place's ID.
-
label(optional):
string
Place's label.
-
links:
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
modifiedBy(optional):
string
User who last modified the place.
-
modifiedOn(optional):
string
When the place was last modified.
-
name:
string
User-defined name for the place.
-
parentPlace(optional):
number
Place ID of the place's parent.
object
Place's Address
object
Attributes
array
0
-
Array of:
object Place
Title:
Place
The long format includes all properties. The short format contains only `id`, `name`, `description`, `children`, and `label`. The short format applies to `POST /mobile/platform/location/places` responses only.
array
0
-
Array of:
object Location Device
Title:
Location Device
The properties for a location device. The long format includes all properties. The short format applies to `POST /mobile/platform/location/devices` responses only.
array
0
-
Array of:
object Associated Location Device
Title:
Associated Location Device
The properties for an associated location device. Note that this object doesn't contain the `asset` and `place` properties.
array
Relationship links
1
true
-
Array of:
object Link
Title:
Link
object
-
latitude(optional):
number
GPS point's latitude
-
longitude(optional):
number
GPS point's longitude.
object
-
latitude(optional):
number
Latitude of the center of the GPS circle.
-
longitude(optional):
number
Longitude of the center of the GPS circle.
-
radius(optional):
number
GPS circle's radius in meters.
object
-
vertices(optional):
array vertices
Minimum Number of Items:
1
GPS polygon's vertices.
array
1
-
Array of:
object latitudeLongitudePair
Pair of latitude and longitude values for a place.
object
-
latitude(optional):
number
Place's latitude.
-
longitude(optional):
number
Place's longitude.
object
Location Device
-
asset(optional):
object Associated Asset
Title:
Associated Asset
The properties for an associated asset. This object doesn't include the `devices` property because the associated device is the containing object. -
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
beacon(optional):
object Beacon
Title:
Beacon
Device's identifying information. -
createdBy:
string
User who added the device.
-
createdOn:
string
When the device was added.
-
description:
string
Device's description.
-
id:
number
Device's ID.
-
links:
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
modifiedBy(optional):
string
User who last modified the device.
-
modifiedOn(optional):
string
When the device was last modified.
-
name:
string
User-defined name for the device.
-
place(optional):
object Associated Place
Title:
Associated Place
The properties for an associated place. This object doesn't include the `devices` property because the associated device is the containing object.
object
Associated Asset
-
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
createdBy:
string
User who added the asset.
-
createdOn:
string
When the asset was added to MCS.
-
description:
string
Asset's description.
-
id:
number
Asset's ID.
-
label(optional):
string
Asset's label.
-
lastKnownLocation(optional):
object Last Known Location
Title:
Last Known Location
Last known location of the asset. -
links:
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
modifiedBy(optional):
string
User who last modified the asset.
-
modifiedOn(optional):
string
When the asset was last modified.
-
name:
string
User-defined name for the asset.
object
Beacon
object
Associated Place
-
address(optional):
object Place's Address
Title:
Place's Address
GPS address of the place. -
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
createdBy:
string
User who added the place.
-
createdOn:
string
When the place was added to MCS.
-
description:
string
Place's description.
-
hasChildren(optional):
boolean
Set to `true` if this place is a parent of other places.
-
id:
number
Place's ID.
-
label(optional):
string
Place's label.
-
links:
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
modifiedBy(optional):
string
User who last modified the place.
-
modifiedOn(optional):
string
When the place was last modified.
-
name:
string
User-defined name for the place.
-
parentPlace(optional):
number
Place's parent place.
object
Last Known Location
object
-
major(optional):
string
Device's major version number.
-
minor(optional):
string
Device's minor version number.
-
uuid(optional):
string
Device's UUID.
object
-
id1(optional):
string
Device's first ID.
-
id2(optional):
string
Device's second ID.
-
id3(optional):
string
Device's third ID.
object
-
eddystoneUid(optional):
object eddystoneUid
Device's UID.
-
eddystoneUrl(optional):
object eddystoneUrl
Device's URL.
object
-
instance(optional):
string
Individual device's ID.
-
namespace(optional):
string
Namespace that the device is a member of.
object
Associated Location Device
-
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
beacon(optional):
object Beacon
Title:
Beacon
Device's identifying information. -
createdBy:
string
User who added the device.
-
createdOn:
string
When the device was added to MCS.
-
description:
string
Device's description.
-
id:
number
Device's ID.
-
links:
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
modifiedBy(optional):
string
User who last modified the device.
-
modifiedOn(optional):
string
When the device was last modified.
-
name:
string
User-defined name for the device.
object
Link
-
href:
string
A relative URL.
-
rel:
Allowed Values:
[ "self", "canonical", "prev", "next" ]
The type of link.
{
"limit":2,
"hasMore":true,
"count":2,
"items":[
{
"createdOn":"2015-08-06T18:37:59.424Z",
"id":112,
"modifiedOn":"2015-08-06T18:37:59.424Z",
"hasChildren":false,
"createdBy":"jdoe",
"address":{
"gpsPoint":{
"longitude":37,
"latitude":122
}
},
"description":"FixItFast Warehouse in Redwood City",
"modifiedBy":"jdoe",
"name":"FixItFast Redwood City Warehouse",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/places/112"
},
{
"rel":"self",
"href":"/mobile/platform/location/places/112"
}
],
"label":"FixItFast Warehouse",
"attributes":{
"hours":"9am-6pm"
},
"devices":[
{
"id":12345,
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"createdBy":"jdoe",
"modifiedBy":"tsmith",
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City",
"name":"RC_WH_01_F01_B001",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/12345"
},
{
"rel":"self",
"href":"/mobile/platform/location/devices/12345"
}
],
"beacon":{
"iBeacon":{
"minor":"1.1",
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0"
}
},
"attributes":{
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public",
"manufacturer":"Abc Company"
}
}
],
"parentPlace":42
},
{
"createdOn":"2015-08-06T19:27:59.424Z",
"id":325,
"modifiedOn":"2015-08-06T19:27:59.424Z",
"hasChildren":false,
"createdBy":"jdoe",
"address":{
"gpsCircle":{
"longitude":37,
"radius":300,
"latitude":123
}
},
"description":"FixItFast Warehouse in Palo Alto",
"modifiedBy":"jdoe",
"name":"FixItFast Palo Alto Warehouse",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/places/325"
},
{
"rel":"self",
"href":"/mobile/platform/location/places/325"
}
],
"label":"FixItFast Warehouse",
"attributes":{
"hours":"9am-6pm"
},
"devices":[
{
"id":111,
"createdOn":"2015-08-06T18:37:59.424Z",
"modifiedOn":"2015-08-08T07:22:44.654Z",
"createdBy":"jdoe",
"modifiedBy":"tsmith",
"description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City",
"name":"RC_WH_01_F01_B001",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/111"
},
{
"rel":"self",
"href":"/mobile/platform/location/devices/111"
}
],
"beacon":{
"iBeacon":{
"minor":"1.1",
"uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
"major":"1.0"
}
},
"attributes":{
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public",
"manufacturer":"Abc Company"
}
},
{
"id":222,
"createdOn":"2015-08-08T18:37:59.424Z",
"modifiedOn":"2015-08-12T07:22:44.654Z",
"createdBy":"jdoe",
"modifiedBy":"tsmith",
"description":"Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
"name":"RC_WH_01_F01_B996",
"links":[
{
"rel":"canonical",
"href":"/mobile/platform/location/devices/222"
},
{
"rel":"self",
"href":"/mobile/platform/location/devices/222"
}
],
"beacon":{
"iBeacon":{
"minor":"1.1",
"uuid":"B9407F30-F5F8-466E-AFF9-25552345908234DD0",
"major":"1.0"
}
},
"attributes":{
"manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
"status":"Active",
"visibility":"Public",
"manufacturer":"Abc Company"
}
}
],
"parentPlace":42
}
],
"totalResults":203,
"offset":0
}
400 Response
The request failed because the JSON payload for the query is not well-formed, or because an exception occurred during processing.
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
Examples
This example shows how to use cURL to retrieve information about places by submitting a POST request on the REST resource.
curl -i \
-X POST \
-u mobile.user@example.com:password \
-d @places.json \
-H "Content-Type: application/json; charset=utf-8" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
https://fif.cloud.oracle.com/mobile/platform/location/places/query
Example of Request Body
Here's an example of the request body in JSON format. This example requests, in ascending name
order, information about all the places where the label
includes the string block
(case-insensitive match) and that are in a defined circle with the specified radius where the center is at the given latitude and longitude. This request asks for the first 2 search results. If you subsequently want to get the next set of places, starting with the 3rd place, you would send another request with the offset
set to 2
. Note that, by default, it's requesting both root and child places, and it's requesting the long
format of the response body.
{ "label":"block",
"inGeoFence":{
"gpsCircle":{
"longitude":-120.8745,
"latitude":37.9856,
"radius":180000
}
},
"orderBy":"name:asc",
"offset":0,
"limit":2
}
Example of Response Header
Here's an example of the response header:
200 OK
Content-Type: application/json
Date: Thu, 19 Apr 2018 22:15:15 GMT
Example of Response Body
This example shows the contents of the response body in JSON format, which is an array of the matching items. Note that by default, it shows all parent and child places.
{
"items": [
{
"id": 10,
"createdOn": "2018-04-19T21:42:07.506Z",
"createdBy": "mobile.user@example.com",
"modifiedOn": "2018-04-19T21:42:07.506Z",
"modifiedBy": "mobile.user@example.com",
"name": "l1b1",
"label": "lot 1 block 1",
"description": "Lot 1 block 1 New City",
"hasChildren": true,
"address": {
"gpsCircle": {
"longitude": -120.8745,
"latitude": 37.9856,
"radius": 29999.99999998
}
},
"attributes": {
"acres": ".25"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/10"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/10"
}
],
"children": [
{
"id": 12,
"createdOn": "2018-04-19T21:51:06.772Z",
"createdBy": "mobile.user@example.com",
"modifiedOn": "2018-04-19T21:51:06.772Z",
"modifiedBy": "mobile.user@example.com",
"name": "s1l1b1",
"label": "sublot 1 lot 1 block 1",
"parentPlace": 10,
"description": "Sublot 1 Lot 1 block 1 New City",
"hasChildren": true,
"address": {
"gpsCircle": {
"longitude": -120.8745,
"latitude": 37.9856,
"radius": 29999.99999998
}
},
"attributes": {
"acres": ".1"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/12"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/12"
}
],
"children": [
{
"id": 13,
"createdOn": "2018-04-19T21:53:20.548Z",
"createdBy": "mobile.user@example.com",
"modifiedOn": "2018-04-19T21:53:20.548Z",
"modifiedBy": "mobile.user@example.com",
"name": "s2l1b1",
"label": "sublot 2 lot 1 block 1",
"parentPlace": 12,
"description": "Sublot 2 Lot 1 block 1 New City",
"hasChildren": false,
"address": {
"gpsCircle": {
"longitude": -120.8745,
"latitude": 37.9856,
"radius": 29999.99999998
}
},
"attributes": {
"acres": ".1"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/13"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/13"
}
],
"children": []
}
]
}
]
},
{
"id": 11,
"createdOn": "2018-04-19T21:42:07.529Z",
"createdBy": "mobile.user@example.com",
"modifiedOn": "2018-04-19T21:42:07.529Z",
"modifiedBy": "mobile.user@example.com",
"name": "l2b1",
"label": "lot2 block 1",
"description": "Lot 2 block 1 New City",
"hasChildren": false,
"address": {
"gpsPolygon": {
"vertices": [
{
"longitude": -121.7845,
"latitude": 37.8453
},
{
"longitude": -120.9853,
"latitude": 37.1248
},
{
"longitude": -121.7758,
"latitude": 37.6983
}
]
}
},
"attributes": {
"acres": ".25"
},
"links": [
{
"rel": "canonical",
"href": "/mobile/platform/location/places/11"
},
{
"rel": "self",
"href": "/mobile/platform/location/places/11"
}
],
"children": []
}
],
"totalResults": 4,
"offset": 0,
"limit": 2,
"count": 2,
"hasMore": true
}
Here's an example of the response body when the request body includes "format": "short"
. The response body includes id
, name
, description
, and children
only.
{
"items": [
{
"id": 10,
"name": "l1b1",
"description": "Lot 1 block 1 New City",
"label": "lot 1 block 1",
"children": [
{
"id": 12,
"name": "s1l1b1",
"description": "Sublot 1 Lot 1 block 1 New City",
"label": "sublot 1 lot 1 block 1",
"children": [
{
"id": 13,
"name": "s2l1b1",
"description": "Sublot 2 Lot 1 block 1 New City",
"label": "sublot 2 lot 1 block 1",
"children": []
}
]
}
]
},
{
"id": 11,
"name": "l2b1",
"description": "Lot 2 block 1 New City",
"label": "lot2 block 1",
"children": []
}
],
"totalResults": 4,
"offset": 0,
"limit": 2,
"count": 2,
"hasMore": true
}