Return Devices by Query
/mobile/platform/location/devices/query
Returns the location devices that match the query parameters that you specify in the request body. If the devices are associated with a place, then the response contains the associated place IDs.
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
-
altBeacon_id1(optional):
string
Return all the altBeacon devices with this `id1`.
-
altBeacon_id2(optional):
string
Return all the altBeacon devices with this `id2`.
-
altBeacon_id3(optional):
string
Return all the altBeacon devices with this `id3`.
-
associatedAssetId(optional):
integer
Return all the devices associated with this asset ID. When you use this query parameter, don't combine it with other parameters.
-
attributes(optional):
object Attributes
Title:
Attributes
Additional Properties Allowed: additionalPropertiesThe attributes entered in the MCS UI, as key/value pairs. -
description(optional):
string
Filter results based on a partial match of this string with the device's description.
-
eddystone_instance(optional):
string
Return all the eddystone devices with this instance.
-
eddystone_namespace(optional):
string
Return all the eddystone devices with this name space.
-
eddystone_url(optional):
string
Return all the eddystone devices with this URL.
-
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`, and `protocol` properties. -
iBeacon_major(optional):
string
Return all the iBeacon devices with this major version.
-
iBeacon_minor(optional):
string
Return all the iBeacon devices with this minor version.
-
iBeacon_uuid(optional):
string
Return all the iBeacon devices with this UUID.
-
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. -
listOfDevices(optional):
array listOfDevices
Device ID(s) to search for. Example: `[15,16]`.
-
name(optional):
string
Filter results based on a partial match of this string with the device's user-defined name.
-
offset(optional):
integer
Default Value:
0
Zero-based index of the first item to return. -
orderBy(optional):
string
Allowed Values:
[ "name", "createdOn", "modifiedOn" ]
Field to order results by. Requires either `:asc` for ascending or `:desc` for descending. Example: `createdOn:asc`. -
protocol(optional):
string
Allowed Values:
[ "iBeacon", "altBeacon", "eddystone" ]
Return all the devices with this protocol. -
search(optional):
string
Filter results based on a case-insensitive partial match of this string with either the device's name or description.
object
Attributes
array
{
"limit":5,
"protocol":"altBeacon",
"orderBy":"name:asc",
"search":"Warehouse",
"format":"short",
"offset":0
}
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
Devices 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 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.
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
Attributes
object
Beacon
array
Relationship links
1
true
-
Array of:
object Link
Title:
Link
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
-
latitude(optional):
number
GPS point's latitude
-
longitude(optional):
number
GPS point's longitude.
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
Link
-
href:
string
A relative URL.
-
rel:
Allowed Values:
[ "self", "canonical", "prev", "next" ]
The type of link.
object
Place's Address
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.
{
"limit":5,
"hasMore":false,
"count":5,
"items":[
{
"id":33,
"protocol":"altBeacon",
"description":"Beacon on 2nd Floor NW in FixItFast Warehouse in Redwood City",
"name":"RC_WH_01_B09_C004"
},
{
"id":12,
"protocol":"altBeacon",
"description":"Beacon on 1st Floor SE in FixItFast Warehouse in Redwood City",
"name":"RC_WH_01_F01_B001"
},
{
"id":61,
"protocol":"altBeacon",
"description":"Beacon on 2nd Floor SW in FixItFast Warehouse in Redwood City",
"name":"RC_WH_01_F01_B008"
},
{
"id":58,
"protocol":"altBeacon",
"description":"Beacon on 1st Floor NW in FixitFast Warehouse in Redwood City",
"name":"RC_WH_02_F01_B011"
},
{
"id":114,
"protocol":"altBeacon",
"description":"Beacon on 3rd Floor NW in FixitFast Warehouse in Redwood City",
"name":"RC_WH_01_K22_A999"
}
],
"totalResults":50,
"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 location devices by submitting a POST request on the REST resource.
curl -i \
-X POST \
-u mobile.user@example.com:password \
-d @iBeacon.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/devices/query
Examples of Request Body
Here's an example of the request body in JSON format. This example requests, in ascending name order, information about the first 5 altBeacon devices that have a name
or description
that contains the string warehouse
(case-insensitive match). Note that it's requesting the short
format. Therefore, only the id
, name
, description
, and protocol
fields are returned.
{
"protocol":"altBeacon",
"orderBy":"name:asc",
"offset":0,
"limit":5,
"format":"short",
"search":"Warehouse"
}
This example requests information about an iBeacon device with the specified major, minor, and unique IDs.
{
"protocol":"iBeacon",
"iBeacon_major": "2.0",
"iBeacon_minor": "2.2",
"iBeacon_uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"
}
Example of Response Header
Here's an example of the response header:
200 OK
Content-Length: 2087
Content-Type: application/json
Date: Tue, 16 Jun 2015 01:39:07 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:
{
"items":[
{
"id":33,
"name":"RC_WH_01_B09_C004",
"description":"Beacon on 2nd Floor NW in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":12,
"name":"RC_WH_01_F01_B001",
"description":"Beacon on 1st Floor SE in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":61,
"name":"RC_WH_01_F01_B008",
"description":"Beacon on 2nd Floor SW in FixItFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":58,
"name":"RC_WH_02_F01_B011",
"description":"Beacon on 1st Floor NW in FixitFast Warehouse in Redwood City",
"protocol":"altBeacon"},
{
"id":114,
"name":"RC_WH_01_K22_A999",
"description":"Beacon on 3rd Floor NW in FixitFast Warehouse in Redwood City",
"protocol":"altBeacon"}
],
"totalResults":50,
"offset":0,
"limit":5,
"count":5,
"hasMore":false
}