Return Places by Query
post
/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
Supported Media Types
- application/json
Root Schema : Query Parameters
Type:
objectTitle:
Show Source
Query Parameters-
attributes(optional):
object Attributes
Title:
AttributesAdditional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
descendantDevices(optional):
boolean
Default Value:
falseSet 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:
longAllowed 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:
allAllowed 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:
0Maximum Value:500Default Value:40Maximum 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:
0Zero-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.
Nested Schema : Attributes
Type:
objectTitle:
AttributesAdditional Properties Allowed
Show Source
The attributes entered in the MCS UI, as key/value pairs.
Show Source
Nested Schema : gpsCircle
Type:
objectGPS circle.
Show Source
-
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.
Nested Schema : listOfPlaces
Type:
arrayPlace ID(s) to search for. For example `[15,16]`.
Show Source
Nested Schema : gpsPoint
Type:
objectGPS point.
Show Source
-
latitude(optional):
number
GPS point's latitude
-
longitude(optional):
number
GPS point's longitude.
Example Request (application/json)
{
"limit":2,
"orderBy":"name:asc",
"format":"long",
"offset":0,
"inGeoFence":{
"gpsCircle":{
"longitude":122.262,
"radius":180000,
"latitude":37.4996
}
}
}Response
Supported Media Types
- application/json
200 Response
The places that matched the query parameters were retrieved successfully.
Root Schema : Query Results
Type:
objectTitle:
Show Source
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:
1Places 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.
Nested Schema : items
Type:
arrayMinimum Number of Items:
1Places found.
Show Source
-
Array of:
object Place
Title:
PlaceThe 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.
Nested Schema : Place
Type:
objectTitle:
PlaceThe 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.
Show Source
-
address(optional):
object Place's Address
Title:
Place's AddressGPS address of the place. -
attributes(optional):
object Attributes
Title:
AttributesAdditional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
children(optional):
array children
Minimum Number of Items:
0Places 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:
0Devices 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:
0Devices 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 linksMinimum Number of Items:1Unique 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.
Nested Schema : Place's Address
Type:
objectTitle:
Place's AddressGPS address of the place.
Match One
Show Source
Nested Schema : Attributes
Type:
objectTitle:
AttributesAdditional Properties Allowed
Show Source
The attributes entered in the MCS UI, as key/value pairs.
Show Source
Nested Schema : children
Type:
arrayMinimum Number of Items:
0Places that are the child places of this place. This includes the full hierarchy of places that descend from this place.
Show Source
-
Array of:
object Place
Title:
PlaceThe 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.
Nested Schema : descendantDevices
Type:
arrayMinimum Number of Items:
0Devices 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.
Show Source
-
Array of:
object Location Device
Title:
Location DeviceThe properties for a location device. The long format includes all properties. The short format applies to `POST /mobile/platform/location/devices` responses only.
Nested Schema : devices
Type:
arrayMinimum Number of Items:
0Devices associated with this asset. Typically one device, but there can be multiple devices.
Show Source
-
Array of:
object Associated Location Device
Title:
Associated Location DeviceThe properties for an associated location device. Note that this object doesn't contain the `asset` and `place` properties.
Nested Schema : Relationship links
Type:
arrayTitle:
Relationship linksMinimum Number of Items:
1Unique Items Required:
Show Source
true-
Array of:
object Link
Title:
Link
Nested Schema : gpsPoint
Type:
objectGPS point.
Show Source
-
latitude(optional):
number
GPS point's latitude
-
longitude(optional):
number
GPS point's longitude.
Nested Schema : gpsCircle
Type:
objectGPS circle.
Show Source
-
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.
Nested Schema : gpsPolygon
Type:
objectGPS polygon.
Show Source
-
vertices(optional):
array vertices
Minimum Number of Items:
1GPS polygon's vertices.
Nested Schema : vertices
Type:
arrayMinimum Number of Items:
1GPS polygon's vertices.
Show Source
-
Array of:
object latitudeLongitudePair
Pair of latitude and longitude values for a place.
Nested Schema : latitudeLongitudePair
Type:
objectPair of latitude and longitude values for a place.
Show Source
-
latitude(optional):
number
Place's latitude.
-
longitude(optional):
number
Place's longitude.
Nested Schema : Location Device
Type:
objectTitle:
Location DeviceThe properties for a location device. The long format includes all properties. The short format applies to `POST /mobile/platform/location/devices` responses only.
Show Source
-
asset(optional):
object Associated Asset
Title:
Associated AssetThe 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:
AttributesAdditional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
beacon(optional):
object Beacon
Title:
BeaconDevice'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 linksMinimum Number of Items:1Unique 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 PlaceThe properties for an associated place. This object doesn't include the `devices` property because the associated device is the containing object.
Nested Schema : Associated Asset
Type:
objectTitle:
Associated AssetThe properties for an associated asset. This object doesn't include the `devices` property because the associated device is the containing object.
Show Source
-
attributes(optional):
object Attributes
Title:
AttributesAdditional 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 LocationLast known location of the asset. -
links:
array Relationship links
Title:
Relationship linksMinimum Number of Items:1Unique 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.
Nested Schema : Beacon
Type:
objectTitle:
BeaconDevice's identifying information.
Match One
Show Source
Nested Schema : Associated Place
Type:
objectTitle:
Associated PlaceThe properties for an associated place. This object doesn't include the `devices` property because the associated device is the containing object.
Show Source
-
address(optional):
object Place's Address
Title:
Place's AddressGPS address of the place. -
attributes(optional):
object Attributes
Title:
AttributesAdditional 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 linksMinimum Number of Items:1Unique 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.
Nested Schema : Last Known Location
Type:
objectTitle:
Last Known LocationLast known location of the asset.
Match One
Show Source
Nested Schema : iBeacon
Type:
objectiBeacon device.
Show Source
-
major(optional):
string
Device's major version number.
-
minor(optional):
string
Device's minor version number.
-
uuid(optional):
string
Device's UUID.
Nested Schema : altBeacon
Type:
objectAltBeacon device.
Show Source
-
id1(optional):
string
Device's first ID.
-
id2(optional):
string
Device's second ID.
-
id3(optional):
string
Device's third ID.
Nested Schema : eddystone
Type:
objectEddystone device.
Show Source
-
eddystoneUid(optional):
object eddystoneUid
Device's UID.
-
eddystoneUrl(optional):
object eddystoneUrl
Device's URL.
Nested Schema : eddystoneUid
Type:
objectDevice's UID.
Show Source
-
instance(optional):
string
Individual device's ID.
-
namespace(optional):
string
Namespace that the device is a member of.
Nested Schema : Associated Location Device
Type:
objectTitle:
Associated Location DeviceThe properties for an associated location device. Note that this object doesn't contain the `asset` and `place` properties.
Show Source
-
attributes(optional):
object Attributes
Title:
AttributesAdditional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
beacon(optional):
object Beacon
Title:
BeaconDevice'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 linksMinimum Number of Items:1Unique 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.
Nested Schema : Link
Type:
objectTitle:
Show Source
Link-
href:
string
A relative URL.
-
rel:
Allowed Values:
[ "self", "canonical", "prev", "next" ]The type of link.
Example Response (application/json)
{
"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.
Root Schema : Error
Type:
objectTitle:
ErrorThe error JSON object returned by Mobile Cloud Service.
Show Source
-
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:
0List 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.
Nested Schema : o:errorDetails
Type:
arrayMinimum Number of Items:
0List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
-
Array of:
object Error Detail
Title:
Error Detail
Nested Schema : Error Detail
Type:
objectTitle:
Show Source
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/queryExample 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
}