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

Request

Supported Media Types

• application/json

Body ()

Root Schema : Query Parameters

Type: object

Title: Query Parameters

Show Source

• attributes: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• descendantDevices: 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: 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: string
  Filter results based on a case-insensitive partial match of this string with the place's description.
• format: 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.
• inGeoFence: object gpsCircle
  GPS circle.
• label: string
  Filter results based on a partial match of this string with the label.
• limit: integer
  Minimum Value: 0

  Maximum Value: 100

  Default Value: 40

  Maximum number of items to return (between 0 and 100). If the requested limit is greater than `100`, then `100` is substituted.
• listOfPlaces: array listOfPlaces
  Place ID(s) to search for. For example `[15,16]`.
• name: string
  Filter results based on a case-insensitive partial match of this string with the place's user-defined name.
• nearestTo: object gpsPoint
  GPS point.
• offset: integer
  Default Value: 0

  Zero-based index of the first item to return.
• orderBy: 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: string
  Filter results based on a case-insensitive partial match of this string with either the place's name or description.

{
    "title":"Query Parameters",
    "type":"object",
    "properties":{
        "offset":{
            "default":0,
            "description":"Zero-based index of the first item to return.",
            "type":"integer"
        },
        "inGeoFence":{
            "description":"Return all the places within this geofence.  When you use this query parameter, don't combine it with other parameters.",
            "$ref":"#/definitions/gpsCircle"
        },
        "format":{
            "default":"long",
            "description":"The response is in long format by default. Specify `short` to return only the `id`, `name`, `description`, and `protocol` properties.",
            "type":"string",
            "enum":[
                "short",
                "long"
            ]
        },
        "orderBy":{
            "description":"Field to order results by. Requires either `:asc` for ascending or `:desc` for descending. Example: `createdOn:asc`.",
            "type":"string",
            "enum":[
                "name",
                "label",
                "createdOn",
                "modifiedOn"
            ]
        },
        "description":{
            "description":"Filter results based on a case-insensitive partial match of this string with the place's description.",
            "type":"string"
        },
        "label":{
            "description":"Filter results based on a partial match of this string with the label.",
            "type":"string"
        },
        "descendantDevices":{
            "default":false,
            "description":"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.",
            "type":"boolean"
        },
        "descendantsOf":{
            "description":"Return places that are direct descendants of this place ID. When you use this query parameter, don't combine it with other parameters.",
            "type":"number"
        },
        "nearestTo":{
            "description":"Return the place that's closest to this GPS point.  When you use this query parameter, don't combine it with other parameters.",
            "$ref":"#/definitions/gpsPoint"
        },
        "search":{
            "description":"Filter results based on a case-insensitive partial match of this string with either the place's name or description.",
            "type":"string"
        },
        "name":{
            "description":"Filter results based on a case-insensitive partial match of this string with the place's user-defined name.",
            "type":"string"
        },
        "limit":{
            "default":40,
            "description":"Maximum number of items to return (between 0 and 100). If the requested limit is greater than `100`, then `100` is substituted.",
            "maximum":100,
            "type":"integer",
            "minimum":0
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "listOfPlaces":{
            "description":"Place ID(s) to search for. For example `[15,16]`.",
            "type":"array",
            "items":{
                "type":"number"
            }
        }
    }
}

Nested Schema : Attributes

Type: object

Title: Attributes

Additional Properties Allowed

Show Source

• string

{
    "description":"The attributes entered in the UI, as key/value pairs.",
    "additionalProperties":{
        "type":"string"
    },
    "title":"Attributes",
    "type":"object",
    "properties":{
    }
}

The attributes entered in the UI, as key/value pairs.

Show Source

{
    "description":"The attributes entered in the UI, as key/value pairs.",
    "additionalProperties":{
        "type":"string"
    },
    "title":"Attributes",
    "type":"object",
    "properties":{
    }
}

Nested Schema : gpsCircle

Type: object

GPS circle.

Show Source

• latitude: number
  Latitude of the center of the GPS circle.
• longitude: number
  Longitude of the center of the GPS circle.
• radius: number
  GPS circle's radius in meters.

{
    "description":"GPS circle.",
    "type":"object",
    "properties":{
        "latitude":{
            "description":"Latitude of the center of the GPS circle.",
            "type":"number"
        },
        "radius":{
            "description":"GPS circle's radius in meters.",
            "type":"number"
        },
        "longitude":{
            "description":"Longitude of the center of the GPS circle.",
            "type":"number"
        }
    }
}

Nested Schema : listOfPlaces

Type: array

Place ID(s) to search for. For example `[15,16]`.

Show Source

• [0]: number

{
    "description":"Place ID(s) to search for. For example `[15,16]`.",
    "type":"array",
    "items":{
        "type":"number"
    }
}

Nested Schema : gpsPoint

Type: object

GPS point.

Show Source

• latitude: number
  GPS point's latitude
• longitude: number
  GPS point's longitude.

{
    "description":"GPS point.",
    "type":"object",
    "properties":{
        "latitude":{
            "description":"GPS point's latitude",
            "type":"number"
        },
        "longitude":{
            "description":"GPS point's longitude.",
            "type":"number"
        }
    }
}

Example Request (application/json)

{
    "offset":0,
    "inGeoFence":{
        "gpsCircle":{
            "latitude":37.4996,
            "radius":180000,
            "longitude":122.262
        }
    },
    "limit":2,
    "format":"long",
    "orderBy":"name:asc"
}

Response

Supported Media Types

• application/json

200 Response

The places that matched the query parameters were retrieved successfully.

Body ()

Root Schema : Query Results

Type: object

Title: Query Results

Show Source

• count: integer
  Number of items in this response.
• hasMore: boolean
  `true` if there are more items to return.
• items: array items
  Minimum Number of Items: 1

  Places found.
• limit: integer
  Limit requested.
• offset: integer
  Offset (starting index) requested for this response.
• totalResults: integer
  Number of items that match the query.

{
    "title":"Query Results",
    "type":"object",
    "properties":{
        "totalResults":{
            "description":"Number of items that match the query.",
            "type":"integer"
        },
        "offset":{
            "description":"Offset (starting index) requested for this response.",
            "type":"integer"
        },
        "limit":{
            "description":"Limit requested.",
            "type":"integer"
        },
        "count":{
            "description":"Number of items in this response.",
            "type":"integer"
        },
        "hasMore":{
            "description":"`true` if there are more items to return.",
            "type":"boolean"
        },
        "items":{
            "minItems":1,
            "description":"Places found.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/placeFound"
            }
        }
    }
}

Nested Schema : items

Type: array

Minimum Number of Items: 1

Places found.

Show Source

• [0]: object Place
  Title: Place

  The long format includes all properties. The short format contains only `id`, `name`, `description`, and `label`. The short format applies to `POST /mobile/platform/location/places` responses only.

{
    "minItems":1,
    "description":"Places found.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/placeFound"
    }
}

Nested Schema : Place

Type: object

Title: Place

The long format includes all properties. The short format contains only `id`, `name`, `description`, and `label`. The short format applies to `POST /mobile/platform/location/places` responses only.

Show Source

• address: object Place's Address
  Title: Place's Address

  GPS address of the place.
• attributes: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• children: 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: 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: array devices
  Minimum Number of Items: 0

  Devices associated with this asset. Typically one device, but there can be multiple devices.
• hasChildren: boolean
  Set to `true` if this place is a parent of other places.
• id: number
  Place's ID.
• label: string
  Place's label.
• links: array Relationship links
  Title: Relationship links

  Minimum Number of Items: 1

  Unique Items Required: true
• modifiedBy: string
  User who last modified the place.
• modifiedOn: string
  When the place was last modified.
• name: string
  User-defined name for the place.
• parentPlace: number
  Place ID of the place's parent.

{
    "description":"The long format includes all properties. The short format contains only `id`, `name`, `description`, and `label`.  The short format applies to `POST /mobile/platform/location/places` responses only.",
    "title":"Place",
    "type":"object",
    "required":[
        "id",
        "createdOn",
        "createdBy",
        "name",
        "description",
        "links"
    ],
    "properties":{
        "address":{
            "$ref":"#/definitions/placeAddress"
        },
        "devices":{
            "minItems":0,
            "description":"Devices associated with this asset. Typically one device, but there can be multiple devices.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/associatedDevice"
            }
        },
        "hasChildren":{
            "description":"Set to `true` if this place is a parent of other places.",
            "type":"boolean"
        },
        "description":{
            "description":"Place's description.",
            "type":"string"
        },
        "label":{
            "description":"Place's label.",
            "type":"string"
        },
        "createdOn":{
            "description":"When the place was added.",
            "type":"string"
        },
        "descendantDevices":{
            "minItems":0,
            "description":"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.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/deviceFound"
            }
        },
        "modifiedOn":{
            "description":"When the place was last modified.",
            "type":"string"
        },
        "children":{
            "minItems":0,
            "description":"Places that are the child places of this place. This includes the full hierarchy of places that descend from this place.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/placeFound"
            }
        },
        "createdBy":{
            "description":"User who added the place.",
            "type":"string"
        },
        "parentPlace":{
            "description":"Place ID of the place's parent.",
            "type":"number"
        },
        "name":{
            "description":"User-defined name for the place.",
            "type":"string"
        },
        "modifiedBy":{
            "description":"User who last modified the place.",
            "type":"string"
        },
        "links":{
            "$ref":"#/definitions/links"
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "id":{
            "description":"Place's ID.",
            "type":"number"
        }
    }
}

Nested Schema : Place's Address

Type: object

Title: Place's Address

GPS address of the place.

Match One

Show Source

• object gpsPoint
  GPS point.
• object gpsCircle
  GPS circle.
• object gpsPolygon
  GPS polygon.

{
    "description":"GPS address of the place.",
    "title":"Place's Address",
    "type":"object",
    "x-oneOf":[
        {
            "$ref":"#/definitions/gpsPoint"
        },
        {
            "$ref":"#/definitions/gpsCircle"
        },
        {
            "$ref":"#/definitions/gpsPolygon"
        }
    ]
}

Nested Schema : Attributes

Type: object

Title: Attributes

Additional Properties Allowed

Show Source

• string

{
    "description":"The attributes entered in the UI, as key/value pairs.",
    "additionalProperties":{
        "type":"string"
    },
    "title":"Attributes",
    "type":"object",
    "properties":{
    }
}

The attributes entered in the UI, as key/value pairs.

Show Source

{
    "description":"The attributes entered in the UI, as key/value pairs.",
    "additionalProperties":{
        "type":"string"
    },
    "title":"Attributes",
    "type":"object",
    "properties":{
    }
}

Nested Schema : children

Type: array

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.

Show Source

• [0]: object Place
  Title: Place

  The long format includes all properties. The short format contains only `id`, `name`, `description`, and `label`. The short format applies to `POST /mobile/platform/location/places` responses only.

{
    "minItems":0,
    "description":"Places that are the child places of this place. This includes the full hierarchy of places that descend from this place.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/placeFound"
    }
}

Nested Schema : descendantDevices

Type: array

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.

Show Source

• [0]: 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.

{
    "minItems":0,
    "description":"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.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/deviceFound"
    }
}

Nested Schema : devices

Type: array

Minimum Number of Items: 0

Devices associated with this asset. Typically one device, but there can be multiple devices.

Show Source

• [0]: 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.

{
    "minItems":0,
    "description":"Devices associated with this asset. Typically one device, but there can be multiple devices.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/associatedDevice"
    }
}

Nested Schema : Relationship links

Type: array

Title: Relationship links

Minimum Number of Items: 1

Unique Items Required: true

Show Source

• [0]: object Link
  Title: Link

{
    "minItems":1,
    "uniqueItems":true,
    "title":"Relationship links",
    "type":"array",
    "items":{
        "$ref":"#/definitions/link"
    }
}

Nested Schema : gpsPoint

Type: object

GPS point.

Show Source

• latitude: number
  GPS point's latitude
• longitude: number
  GPS point's longitude.

{
    "description":"GPS point.",
    "type":"object",
    "properties":{
        "latitude":{
            "description":"GPS point's latitude",
            "type":"number"
        },
        "longitude":{
            "description":"GPS point's longitude.",
            "type":"number"
        }
    }
}

Nested Schema : gpsCircle

Type: object

GPS circle.

Show Source

• latitude: number
  Latitude of the center of the GPS circle.
• longitude: number
  Longitude of the center of the GPS circle.
• radius: number
  GPS circle's radius in meters.

{
    "description":"GPS circle.",
    "type":"object",
    "properties":{
        "latitude":{
            "description":"Latitude of the center of the GPS circle.",
            "type":"number"
        },
        "radius":{
            "description":"GPS circle's radius in meters.",
            "type":"number"
        },
        "longitude":{
            "description":"Longitude of the center of the GPS circle.",
            "type":"number"
        }
    }
}

Nested Schema : gpsPolygon

Type: object

GPS polygon.

Show Source

• vertices: array vertices
  Minimum Number of Items: 1

  GPS polygon's vertices.

{
    "description":"GPS polygon.",
    "type":"object",
    "properties":{
        "vertices":{
            "minItems":1,
            "description":"GPS polygon's vertices.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/latitudeLongitudePair"
            }
        }
    }
}

Nested Schema : vertices

Type: array

Minimum Number of Items: 1

GPS polygon's vertices.

Show Source

• [0]: object latitudeLongitudePair
  Pair of latitude and longitude values for a place.

{
    "minItems":1,
    "description":"GPS polygon's vertices.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/latitudeLongitudePair"
    }
}

Nested Schema : latitudeLongitudePair

Type: object

Pair of latitude and longitude values for a place.

Show Source

• latitude: number
  Place's latitude.
• longitude: number
  Place's longitude.

{
    "description":"Pair of latitude and longitude values for a place.",
    "type":"object",
    "properties":{
        "latitude":{
            "description":"Place's latitude.",
            "type":"number"
        },
        "longitude":{
            "description":"Place's longitude.",
            "type":"number"
        }
    }
}

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

• asset: 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: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• beacon: 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: string
  User who last modified the device.
• modifiedOn: string
  When the device was last modified.
• name: string
  User-defined name for the device.
• place: 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.

{
    "description":"The properties for a location device. The long format includes all properties. The short format applies to `POST /mobile/platform/location/devices` responses only.",
    "title":"Location Device",
    "type":"object",
    "required":[
        "id",
        "createdOn",
        "createdBy",
        "name",
        "description",
        "links"
    ],
    "properties":{
        "modifiedOn":{
            "description":"When the device was last modified.",
            "type":"string"
        },
        "beacon":{
            "$ref":"#/definitions/beacon"
        },
        "createdBy":{
            "description":"User who added the device.",
            "type":"string"
        },
        "name":{
            "description":"User-defined name for the device.",
            "type":"string"
        },
        "description":{
            "description":"Device's description.",
            "type":"string"
        },
        "modifiedBy":{
            "description":"User who last modified the device.",
            "type":"string"
        },
        "links":{
            "$ref":"#/definitions/links"
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "place":{
            "description":"The place that contains the device.",
            "$ref":"#/definitions/associatedPlace"
        },
        "id":{
            "description":"Device's ID.",
            "type":"number"
        },
        "asset":{
            "description":"The asset that contains the device.",
            "$ref":"#/definitions/associatedAsset"
        },
        "createdOn":{
            "description":"When the device was added.",
            "type":"string"
        }
    }
}

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

• attributes: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• createdBy: string
  User who added the asset.
• createdOn: string
  When the asset was added.
• description: string
  Asset's description.
• id: number
  Asset's ID.
• label: string
  Asset's label.
• lastKnownLocation: 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: string
  User who last modified the asset.
• modifiedOn: string
  When the asset was last modified.
• name: string
  User-defined name for the asset.

{
    "description":"The properties for an associated asset. This object doesn't include the `devices` property because the associated device is the containing object.",
    "title":"Associated Asset",
    "type":"object",
    "required":[
        "id",
        "createdOn",
        "createdBy",
        "name",
        "description",
        "links"
    ],
    "properties":{
        "modifiedOn":{
            "description":"When the asset was last modified.",
            "type":"string"
        },
        "createdBy":{
            "description":"User who added the asset.",
            "type":"string"
        },
        "lastKnownLocation":{
            "$ref":"#/definitions/lastKnownLocation"
        },
        "name":{
            "description":"User-defined name for the asset.",
            "type":"string"
        },
        "description":{
            "description":"Asset's description.",
            "type":"string"
        },
        "modifiedBy":{
            "description":"User who last modified the asset.",
            "type":"string"
        },
        "links":{
            "$ref":"#/definitions/links"
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "label":{
            "description":"Asset's label.",
            "type":"string"
        },
        "id":{
            "description":"Asset's ID.",
            "type":"number"
        },
        "createdOn":{
            "description":"When the asset was added.",
            "type":"string"
        }
    }
}

Nested Schema : Beacon

Type: object

Title: Beacon

Device's identifying information.

Match One

Show Source

• object iBeacon
  iBeacon device.
• object altBeacon
  AltBeacon device.
• object eddystone
  Eddystone device.

{
    "description":"Device's identifying information.",
    "title":"Beacon",
    "type":"object",
    "x-oneOf":[
        {
            "$ref":"#/definitions/iBeacon"
        },
        {
            "$ref":"#/definitions/altBeacon"
        },
        {
            "$ref":"#/definitions/eddystone"
        }
    ]
}

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

• address: object Place's Address
  Title: Place's Address

  GPS address of the place.
• attributes: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• createdBy: string
  User who added the place.
• createdOn: string
  When the place was added.
• description: string
  Place's description.
• hasChildren: boolean
  Set to `true` if this place is a parent of other places.
• id: number
  Place's ID.
• label: string
  Place's label.
• links: array Relationship links
  Title: Relationship links

  Minimum Number of Items: 1

  Unique Items Required: true
• modifiedBy: string
  User who last modified the place.
• modifiedOn: string
  When the place was last modified.
• name: string
  User-defined name for the place.
• parentPlace: number
  Place's parent place.

{
    "description":"The properties for an associated place. This object doesn't include the `devices` property because the associated device is the containing object.",
    "title":"Associated Place",
    "type":"object",
    "required":[
        "id",
        "createdOn",
        "createdBy",
        "name",
        "description",
        "links"
    ],
    "properties":{
        "address":{
            "$ref":"#/definitions/placeAddress"
        },
        "hasChildren":{
            "description":"Set to `true` if this place is a parent of other places.",
            "type":"boolean"
        },
        "description":{
            "description":"Place's description.",
            "type":"string"
        },
        "label":{
            "description":"Place's label.",
            "type":"string"
        },
        "createdOn":{
            "description":"When the place was added.",
            "type":"string"
        },
        "modifiedOn":{
            "description":"When the place was last modified.",
            "type":"string"
        },
        "createdBy":{
            "description":"User who added the place.",
            "type":"string"
        },
        "parentPlace":{
            "description":"Place's parent place.",
            "type":"number"
        },
        "name":{
            "description":"User-defined name for the place.",
            "type":"string"
        },
        "modifiedBy":{
            "description":"User who last modified the place.",
            "type":"string"
        },
        "links":{
            "$ref":"#/definitions/links"
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "id":{
            "description":"Place's ID.",
            "type":"number"
        }
    }
}

Nested Schema : Last Known Location

Type: object

Title: Last Known Location

Last known location of the asset.

Match One

Show Source

• object gpsPoint
  GPS point.
• integer
  Title: placeId

  ID of the associated place.

{
    "description":"Last known location of the asset.",
    "title":"Last Known Location",
    "type":"object",
    "x-oneOf":[
        {
            "$ref":"#/definitions/gpsPoint"
        },
        {
            "$ref":"#/definitions/placeId"
        }
    ]
}

Nested Schema : iBeacon

Type: object

iBeacon device.

Show Source

• major: string
  Device's major version number.
• minor: string
  Device's minor version number.
• uuid: string
  Device's UUID.

{
    "description":"iBeacon device.",
    "type":"object",
    "properties":{
        "major":{
            "description":"Device's major version number.",
            "type":"string"
        },
        "minor":{
            "description":"Device's minor version number.",
            "type":"string"
        },
        "uuid":{
            "description":"Device's UUID.",
            "type":"string"
        }
    }
}

Nested Schema : altBeacon

Type: object

AltBeacon device.

Show Source

• id1: string
  Device's first ID.
• id2: string
  Device's second ID.
• id3: string
  Device's third ID.

{
    "description":"AltBeacon device.",
    "type":"object",
    "properties":{
        "id2":{
            "description":"Device's second ID.",
            "type":"string"
        },
        "id1":{
            "description":"Device's first ID.",
            "type":"string"
        },
        "id3":{
            "description":"Device's third ID.",
            "type":"string"
        }
    }
}

Nested Schema : eddystone

Type: object

Eddystone device.

Show Source

• eddystoneUid: object eddystoneUid
  Device's UID.
• eddystoneUrl: object eddystoneUrl
  Device's URL.

{
    "description":"Eddystone device.",
    "type":"object",
    "properties":{
        "eddystoneUid":{
            "description":"Device's UID.",
            "type":"object",
            "properties":{
                "instance":{
                    "description":"Individual device's ID.",
                    "type":"string"
                },
                "namespace":{
                    "description":"Namespace that the device is a member of.",
                    "type":"string"
                }
            }
        },
        "eddystoneUrl":{
            "description":"Device's URL.",
            "type":"object",
            "properties":{
                "url":{
                    "description":"The URL.",
                    "type":"string"
                }
            }
        }
    }
}

Nested Schema : eddystoneUid

Type: object

Device's UID.

Show Source

• instance: string
  Individual device's ID.
• namespace: string
  Namespace that the device is a member of.

{
    "description":"Device's UID.",
    "type":"object",
    "properties":{
        "instance":{
            "description":"Individual device's ID.",
            "type":"string"
        },
        "namespace":{
            "description":"Namespace that the device is a member of.",
            "type":"string"
        }
    }
}

Nested Schema : eddystoneUrl

Type: object

Device's URL.

Show Source

• url: string
  The URL.

{
    "description":"Device's URL.",
    "type":"object",
    "properties":{
        "url":{
            "description":"The URL.",
            "type":"string"
        }
    }
}

Nested Schema : Associated Location Device

Type: object

Title: Associated Location Device

The properties for an associated location device. Note that this object doesn't contain the `asset` and `place` properties.

Show Source

• attributes: object Attributes
  Title: Attributes

  Additional Properties Allowed: additionalProperties

  The attributes entered in the UI, as key/value pairs.
• beacon: 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: string
  User who last modified the device.
• modifiedOn: string
  When the device was last modified.
• name: string
  User-defined name for the device.

{
    "description":"The properties for an associated location device. Note that this object doesn't contain the `asset` and `place` properties.",
    "title":"Associated Location Device",
    "type":"object",
    "required":[
        "id",
        "createdOn",
        "createdBy",
        "name",
        "description",
        "links"
    ],
    "properties":{
        "modifiedOn":{
            "description":"When the device was last modified.",
            "type":"string"
        },
        "beacon":{
            "$ref":"#/definitions/beacon"
        },
        "createdBy":{
            "description":"User who added the device.",
            "type":"string"
        },
        "name":{
            "description":"User-defined name for the device.",
            "type":"string"
        },
        "description":{
            "description":"Device's description.",
            "type":"string"
        },
        "modifiedBy":{
            "description":"User who last modified the device.",
            "type":"string"
        },
        "links":{
            "$ref":"#/definitions/links"
        },
        "attributes":{
            "$ref":"#/definitions/objectAttributes"
        },
        "id":{
            "description":"Device's ID.",
            "type":"number"
        },
        "createdOn":{
            "description":"When the device was added.",
            "type":"string"
        }
    }
}

Nested Schema : Link

Type: object

Title: Link

Show Source

• href: string
  A relative URL.
• rel:
  Allowed Values: [ "self", "canonical", "prev", "next" ]

  The type of link.

{
    "title":"Link",
    "type":"object",
    "required":[
        "rel",
        "href"
    ],
    "properties":{
        "rel":{
            "description":"The type of link.",
            "enum":[
                "self",
                "canonical",
                "prev",
                "next"
            ]
        },
        "href":{
            "description":"A relative URL.",
            "type":"string"
        }
    }
}

Example Response (application/json)

{
    "totalResults":203,
    "offset":0,
    "limit":2,
    "count":2,
    "hasMore":true,
    "items":[
        {
            "address":{
                "gpsPoint":{
                    "latitude":122,
                    "longitude":37
                }
            },
            "devices":[
                {
                    "modifiedOn":"2015-08-08T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "major":"1.0",
                            "minor":"1.1",
                            "uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D"
                        }
                    },
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B001",
                    "description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City",
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/12345"
                        },
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/12345"
                        }
                    ],
                    "attributes":{
                        "visibility":"Public",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "manufacturer":"Abc Company",
                        "status":"Active"
                    },
                    "id":12345,
                    "createdOn":"2015-08-06T18:37:59.424Z"
                }
            ],
            "hasChildren":false,
            "description":"FixItFast Warehouse in Redwood City",
            "label":"FixItFast Warehouse",
            "createdOn":"2015-08-06T18:37:59.424Z",
            "modifiedOn":"2015-08-06T18:37:59.424Z",
            "createdBy":"jdoe",
            "parentPlace":42,
            "name":"FixItFast Redwood City Warehouse",
            "modifiedBy":"jdoe",
            "links":[
                {
                    "rel":"canonical",
                    "href":"/mobile/platform/location/places/112"
                },
                {
                    "rel":"self",
                    "href":"/mobile/platform/location/places/112"
                }
            ],
            "attributes":{
                "hours":"9am-6pm"
            },
            "id":112
        },
        {
            "address":{
                "gpsCircle":{
                    "latitude":123,
                    "radius":300,
                    "longitude":37
                }
            },
            "devices":[
                {
                    "modifiedOn":"2015-08-08T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "major":"1.0",
                            "minor":"1.1",
                            "uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D"
                        }
                    },
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B001",
                    "description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City",
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/111"
                        },
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/111"
                        }
                    ],
                    "attributes":{
                        "visibility":"Public",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "manufacturer":"Abc Company",
                        "status":"Active"
                    },
                    "id":111,
                    "createdOn":"2015-08-06T18:37:59.424Z"
                },
                {
                    "modifiedOn":"2015-08-12T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "major":"1.0",
                            "minor":"1.1",
                            "uuid":"B9407F30-F5F8-466E-AFF9-25552345908234DD0"
                        }
                    },
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B996",
                    "description":"Beacon on 2nd Floor in FixitFast Warehouse in Redwood City",
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/222"
                        },
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/222"
                        }
                    ],
                    "attributes":{
                        "visibility":"Public",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "manufacturer":"Abc Company",
                        "status":"Active"
                    },
                    "id":222,
                    "createdOn":"2015-08-08T18:37:59.424Z"
                }
            ],
            "hasChildren":false,
            "description":"FixItFast Warehouse in Palo Alto",
            "label":"FixItFast Warehouse",
            "createdOn":"2015-08-06T19:27:59.424Z",
            "modifiedOn":"2015-08-06T19:27:59.424Z",
            "createdBy":"jdoe",
            "parentPlace":42,
            "name":"FixItFast Palo Alto Warehouse",
            "modifiedBy":"jdoe",
            "links":[
                {
                    "rel":"canonical",
                    "href":"/mobile/platform/location/places/325"
                },
                {
                    "rel":"self",
                    "href":"/mobile/platform/location/places/325"
                }
            ],
            "attributes":{
                "hours":"9am-6pm"
            },
            "id":325
        }
    ]
}

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

• 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
  The service's error code.
• o:errorDetails: 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.

{
    "description":"The error JSON object returned by the service.",
    "title":"Error",
    "type":"object",
    "required":[
        "type",
        "status",
        "title",
        "detail",
        "o:ecid",
        "o:errorCode",
        "o:errorPath"
    ],
    "properties":{
        "o:errorCode":{
            "description":"The service's error code.",
            "type":"string"
        },
        "o:errorDetails":{
            "minItems":0,
            "description":"List of the issues that cause the error. Included when the error is caused by multiple issues.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/errorDetail"
            }
        },
        "detail":{
            "description":"Message that provides the error details.",
            "type":"string"
        },
        "type":{
            "description":"The URI to the link that provides details about the HTTP status code.",
            "type":"string"
        },
        "title":{
            "description":"Summary of the problem.",
            "type":"string"
        },
        "o:errorPath":{
            "description":"The relative point in the API path where the error occurred.",
            "type":"string"
        },
        "o:ecid":{
            "description":"Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.",
            "type":"string"
        },
        "status":{
            "description":"HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.",
            "type":"integer"
        }
    }
}

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

• [0]: object Error Detail
  Title: Error Detail

{
    "minItems":0,
    "description":"List of the issues that cause the error. Included when the error is caused by multiple issues.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/errorDetail"
    }
}

Nested Schema : Error Detail

Type: object

Title: Error Detail

Show Source

• instance: string
  The URI to the link that provides more detailed information about the error.
• o:errorCode: string
  The service's 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.

{
    "title":"Error Detail",
    "type":"object",
    "required":[
        "type",
        "instance",
        "title",
        "o:errorPath",
        "o:errorCode"
    ],
    "properties":{
        "instance":{
            "description":"The URI to the link that provides more detailed information about the error.",
            "type":"string"
        },
        "o:errorCode":{
            "description":"The service's error code.",
            "type":"string"
        },
        "type":{
            "description":"The URI to the link that provides details about the HTTP status code.",
            "type":"string"
        },
        "title":{
            "description":"Summary of the problem.",
            "type":"string"
        },
        "o:errorPath":{
            "description":"The relative point in the API path where the error occurred.",
            "type":"string"
        }
    }
}

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 [e-mail]: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 places where the label includes the string commercial (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 two search results. If you subsequently want to get the next set of places, starting with the third place, you would send another request with the offset set to 2. Note that it is requesting the long format of the response body. If the value was short, then the response body would include id, name, description, and label only.

{
  "label":"commercial",
  "inGeoFence":{
    "gpsCircle":{
      "longitude":122.262,
      "latitude":37.4996,
      "radius":180000
    }
  },
  "orderBy":"name:asc",
  "offset":0,
  "limit":2,
  "format":"long"
}

Example of Response Header

Here's an example of the response header:

200 OK
Content-Length: 1173
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":[
        {
            "devices":[
                {
                    "id":12345,
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B001",
                    "createdOn":"2015-08-06T18:37:59.424Z",
                    "modifiedOn":"2015-08-08T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
                            "major":"1.0",
                            "minor":"1.1"}},
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/12345"},
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/12345"}
                    ],
                    "attributes":{
                        "manufacturer":"Abc Company",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "status":"Active",
                        "visibility":"Public"},
                    "description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"}
            ],
            "label":"FixItFast Warehouse",
            "id":112,
            "createdBy":"jdoe",
            "name":"FixItFast Redwood City Warehouse",
            "createdOn":"2015-08-06T18:37:59.424Z",
            "modifiedOn":"2015-08-06T18:37:59.424Z",
            "address":{
                "gpsPoint":{
                    "latitude":122,
                    "longitude":37}},
            "modifiedBy":"jdoe",
            "links":[
                {
                    "rel":"canonical",
                    "href":"/mobile/platform/location/places/112"},
                {
                    "rel":"self",
                    "href":"/mobile/platform/location/places/112"}
            ],
            "attributes":{
                "hours":"9am-6pm"},
            "hasChildren":false,
            "parentPlace":42,
            "description":"FixItFast Warehouse in Redwood City"},
        {
            "devices":[
                {
                    "id":111,
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B001",
                    "createdOn":"2015-08-06T18:37:59.424Z",
                    "modifiedOn":"2015-08-08T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "uuid":"B9407F30-F5F8-466E-AFF9-25556B57FE6D",
                            "major":"1.0",
                            "minor":"1.1"}},
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/111"},
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/111"}
                    ],
                    "attributes":{
                        "manufacturer":"Abc Company",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "status":"Active",
                        "visibility":"Public"},
                    "description":"Beacon on 1st Floor in FixitFast Warehouse in Redwood City"},
                {
                    "id":222,
                    "createdBy":"jdoe",
                    "name":"RC_WH_01_F01_B996",
                    "createdOn":"2015-08-08T18:37:59.424Z",
                    "modifiedOn":"2015-08-12T07:22:44.654Z",
                    "beacon":{
                        "iBeacon":{
                            "uuid":"B9407F30-F5F8-466E-AFF9-25552345908234DD0",
                            "major":"1.0",
                            "minor":"1.1"}},
                    "modifiedBy":"tsmith",
                    "links":[
                        {
                            "rel":"canonical",
                            "href":"/mobile/platform/location/devices/222"},
                        {
                            "rel":"self",
                            "href":"/mobile/platform/location/devices/222"}
                    ],
                    "attributes":{
                        "manufacturer":"Abc Company",
                        "manufacturerId":"10D39AE7-020E-4467-9CB2-DD36366F899D",
                        "status":"Active",
                        "visibility":"Public"},
                    "description":"Beacon on 2nd Floor in FixitFast Warehouse in Redwood City"}
            ],
            "label":"FixItFast Warehouse",
            "id":325,
            "createdBy":"jdoe",
            "name":"FixItFast Palo Alto Warehouse",
            "createdOn":"2015-08-06T19:27:59.424Z",
            "modifiedOn":"2015-08-06T19:27:59.424Z",
            "address":{
                "gpsCircle":{
                    "latitude":123,
                    "longitude":37,
                    "radius":300}},
            "modifiedBy":"jdoe",
            "links":[
                {
                    "rel":"canonical",
                    "href":"/mobile/platform/location/places/325"},
                {
                    "rel":"self",
                    "href":"/mobile/platform/location/places/325"}
            ],
            "attributes":{
                "hours":"9am-6pm"},
            "hasChildren":false,
            "parentPlace":42,
            "description":"FixItFast Warehouse in Palo Alto"}
    ],
    "totalResults":203,
    "offset":0,
    "limit":2,
    "count":2,
    "hasMore":true
}