Skip to main content

Objects

Create or Update an Object​

POSThttps://api.hivekit.io/v2/realm/[realmId]/object/[objectId]

Creates a new object or updates an existing one.

tip

If you are using IDs with slashes, (e.g. scooter/14) as part of Hivekit's ID pattern functionality, make sure to URL encode them before passing them to the API via the URL.

Request Body​

{ 
    "label": "Scooter #14",  // optional
    "location": {
        "longitude": 12.345, // required longitude in degree
        "latitude": 12.345, // required latitude in degree
        "altitude": 230, // optional altitude in meters above NN
        "speed": 5, // optional speed in m/s
        "heading": 90, // optional heading in degree
        "accuracy": 6, // optional location accuracy in meters
        "altitudeAccuracy": 7, // optional altitude accuracy in meters
        "time": "2021-01-01T12:00:00Z" // optional time of location, expressed as RFC3339Nano
    }
    "data": { // optional
        "charge": 0.7,
    }
}

Response Body​

{
    "result": "success"
}

Create or Update Objects in Bulk​

POSThttps://api.hivekit.io/v2/realm/[realmId]/object

Creates or updates multiple objects at once. You can also use this endpoint to upload the location history for a single object.

tip

If you are using IDs with slashes, (e.g. scooter/14) as part of Hivekit's ID pattern functionality, make sure to URL encode them before passing them to the API via the URL.

Request Body​

{"objects": [{ 
    "id": "scooter/14",  // required
    "label": "Scooter #14",  // optional
    "location": {
        "longitude": 12.345, // required longitude in degree
        "latitude": 12.345, // required latitude in degree
        "altitude": 230, // optional altitude in meters above NN
        "speed": 5, // optional speed in m/s
        "heading": 90, // optional heading in degree
        "accuracy": 6, // optional location accuracy in meters
        "altitudeAccuracy": 7, // optional altitude accuracy in meters
        "time": "2021-01-01T12:00:00Z" // optional time of location, expressed as RFC3339Nano
    },
    "data": { // optional
        "charge": 0.7,
    }
},{ 
    "id": "scooter/15",  // required
    // you can also include partial updates. In this case, only the specified fields will be updated
    "location": {
        "longitude": 12.345, // longitude in degree
        "latitude": 12.345, // latitude in degree
    },
}]}

Response Body​

{
    "result": "success"
}

Read an Object​

GEThttps://api.hivekit.io/v2/realm/[realmId]/object/[objectId]

Response Body​

{
    "id": "scooter/14",
    "label": "Scooter #14",
    "location": {
        "longitude": 12.345,
        "latitude": 12.345,
        "altitude": 230,
        "speed": 5,
        "heading": 90,
        "accuracy": 6,
        "altitudeAccuracy": 7,
        "time": "2021-01-01T12:00:00Z"
    },
    "data": {
        "charge": 0.7
    }
}

List Objects​

GEThttps://api.hivekit.io/v2/realm/[realmId]/object?fields=charge&filter=charge>0.5&shape={"cx":56.78,"cy":14.109 ,"r": 10000}

Lists the objects within a given realm. The list can be filtered based on multiple criteria using the filter parameter and restricted to certain bounds using shape. You can also include additional fields from the object's data in the response using the fields parameter.

tip

If you are looking for a way to fulltext-search for objects instead, have a look at the realm/search endpoint.

Query parameters​

  • fields (optional): A comma-separated list of fields to include in the response. If not specified, only the object's ID and label will be returned.
  • filter (optional): A filter expression to restrict the list of returned objects. The expression can contain any number of conditions, each of which is a field name, followed by a comparison operator, followed by a value. The comparison operators are =, !=, >, <. The value can be a string, number, boolean, or null. The conditions are combined using the logical operator and. The filter expression is case-sensitive.
  • shape (optional): A bounding shape to restrict the list of returned objects. The shape can be a circle, rectangle, or polygon. The shape is specified as a JSON object with the following fields:
    • Circle: {"cx":<longitude>,"cy":<latitude>,"r":<radius in meter>}
    • Rectangle: {"w":<longitude>,"n":<latitude>,"e":<longitude>,"s":<latitude>}
    • Polygon: {"points":[[<longitude>,<latitude>],...]}

Response Body​

{
    "scooter/14": {
        "id": "scooter/14",
        "label": "Scooter 14",
        "data": {
            "charge": 0.2
        },
        "connectionStatus": "dis"
    },
    "scooter/17": {
        "id": "scooter/17",
        "label": "Scooter 17",
        "data": {
            "charge": 0.7
        },
        "connectionStatus": "dis"
    }
}

Examples​

  • List all objects in a realm: GET https://api.hivekit.io/v2/realm/123/object
  • List all objects in a realm and include their charge level and riderId: GET https://api.hivekit.io/v2/realm/123/object?fields=charge,riderId
  • List all objects in a realm with a charge level above 50% that currently have a rider: GET https://api.hivekit.io/v2/realm/123/object?filter=charge>0.5,riderId!=null
  • List all objects in a realm that are within a 10km radius of a given point: GET https://api.hivekit.io/v2/realm/123/object?shape={"cx":56.78,"cy":14.109,"r":10000}
  • List all objects in a realm that are within a given polygon: GET https://api.hivekit.io/v2/realm/123/object?shape={"points":[[56.78,14.109],[56.78,14.119],[56.88,14.119],[56.88,14.109]]}
  • List all objects in a realm that are within a given rectangle: GET https://api.hivekit.io/v2/realm/123/object?shape={"w":56.78,"n":14.109,"e":56.88,"s":14.119}

Delete an Object​

DELETEhttps://api.hivekit.io/v2/realm/[realmId]/object/[objectId]

Response Body​

{
    "result": "success"
}