1. REST API Reference for Oracle Mobile Cloud Enterprise - Platform APIs
  2. Tasks
  3. Location

Return Devices by Query

post

/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 virtual user or a mobile user, then you must have the role that's associated with the mobile backend.

Request

Supported Media Types
Body ()
Root Schema : Query Parameters
Type: object
Title: Query Parameters
Show Source
Nested Schema : Attributes
Type: object
Title: Attributes
Additional Properties Allowed
Show Source
The attributes entered in the UI, as key/value pairs.
Show Source
Nested Schema : listOfDevices
Type: array
Device ID(s) to search for. Example: `[15,16]`.
Show Source
Example Request (application/json)
{
    "protocol":"altBeacon",
    "search":"Warehouse",
    "offset":0,
    "limit":5,
    "format":"short",
    "orderBy":"name:asc"
}

Response

Supported Media Types

200 Response

The location devices that matched the query parameters were retrieved successfully.
Body ()
Root Schema : Query Results
Type: object
Title: Query Results
Show Source
Nested Schema : items
Type: array
Minimum Number of Items: 1
Devices found.
Show Source
  • 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.
Nested Schema : Location Device
Type: object
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.
Show Source
Nested Schema : Associated Asset
Type: object
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.
Show Source
Nested Schema : Attributes
Type: object
Title: Attributes
Additional Properties Allowed
Show Source
The attributes entered in the UI, as key/value pairs.
Show Source
Nested Schema : Beacon
Type: object
Title: Beacon
Device's identifying information.
Match One
Show Source
Nested Schema : Associated Place
Type: object
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.
Show Source
Nested Schema : Last Known Location
Type: object
Title: Last Known Location
Last known location of the asset.
Match One
Show Source
Nested Schema : gpsPoint
Type: object
GPS point.
Show Source
Nested Schema : iBeacon
Type: object
iBeacon device.
Show Source
Nested Schema : altBeacon
Type: object
AltBeacon device.
Show Source
Nested Schema : eddystone
Type: object
Eddystone device.
Show Source
Nested Schema : eddystoneUid
Type: object
Device's UID.
Show Source
Nested Schema : eddystoneUrl
Type: object
Device's URL.
Show Source
Nested Schema : Place's Address
Type: object
Title: Place's Address
GPS address of the place.
Match One
Show Source
Nested Schema : gpsCircle
Type: object
GPS circle.
Show Source
Nested Schema : gpsPolygon
Type: object
GPS polygon.
Show Source
Nested Schema : vertices
Type: array
Minimum Number of Items: 1
GPS polygon's vertices.
Show Source
Nested Schema : latitudeLongitudePair
Type: object
Pair of latitude and longitude values for a place.
Show Source
Example Response (application/json)
{
    "totalResults":50,
    "offset":0,
    "limit":5,
    "count":5,
    "hasMore":false,
    "items":[
        {
            "protocol":"altBeacon",
            "name":"RC_WH_01_B09_C004",
            "description":"Beacon on 2nd Floor NW in FixItFast Warehouse in Redwood City",
            "id":33
        },
        {
            "protocol":"altBeacon",
            "name":"RC_WH_01_F01_B001",
            "description":"Beacon on 1st Floor SE in FixItFast Warehouse in Redwood City",
            "id":12
        },
        {
            "protocol":"altBeacon",
            "name":"RC_WH_01_F01_B008",
            "description":"Beacon on 2nd Floor SW in FixItFast Warehouse in Redwood City",
            "id":61
        },
        {
            "protocol":"altBeacon",
            "name":"RC_WH_02_F01_B011",
            "description":"Beacon on 1st Floor NW in FixitFast Warehouse in Redwood City",
            "id":58
        },
        {
            "protocol":"altBeacon",
            "name":"RC_WH_01_K22_A999",
            "description":"Beacon on 3rd Floor NW in FixitFast Warehouse in Redwood City",
            "id":114
        }
    ]
}

400 Response

The request failed because the JSON payload for the query is not well-formed, or because an exception occurred during processing.

Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
List of the issues that cause the error. Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source

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
}