1"use strict";(self.webpackChunkmy_website=self.webpackChunkmy_website||[]).push([[8029],{5673:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>a,default:()=>h,frontMatter:()=>r,metadata:()=>o,toc:()=>c});var s=i(5893),t=i(1151);const r={sidebar_position:3,title:"Objects"},a=void 0,o={id:"http-api/object",title:"Objects",description:"Create or Update an Object",source:"@site/docs/http-api/object.md",sourceDirName:"http-api",slug:"/http-api/object",permalink:"/docs/http-api/object",draft:!1,unlisted:!1,tags:[],version:"current",sidebarPosition:3,frontMatter:{sidebar_position:3,title:"Objects"},sidebar:"tutorialSidebar",previous:{title:"Realms",permalink:"/docs/http-api/realm"},next:{title:"Areas",permalink:"/docs/http-api/area"}},l={},c=[{value:"Create or Update an Object",id:"create-or-update-an-object",level:3},{value:"Request Body",id:"request-body",level:4},{value:"Response Body",id:"response-body",level:4},{value:"Create or Update Objects in Bulk",id:"create-or-update-objects-in-bulk",level:3},{value:"Request Body",id:"request-body-1",level:4},{value:"Response Body",id:"response-body-1",level:4},{value:"Read an Object",id:"read-an-object",level:3},{value:"Response Body",id:"response-body-2",level:4},{value:"List Objects",id:"list-objects",level:3},{value:"Query parameters",id:"query-parameters",level:4},{value:"Response Body",id:"response-body-3",level:4},{value:"Examples",id:"examples",level:4},{value:"Delete an Object",id:"delete-an-object",level:3},{value:"Response Body",id:"response-body-4",level:4}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h3:"h3",h4:"h4",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.a)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.h3,{id:"create-or-update-an-object",children:"Create or Update an Object"}),"\n",(0,s.jsxs)("div",{class:"rest-api-header",children:[(0,s.jsx)("span",{class:"post method",children:"POST"}),(0,s.jsxs)("span",{class:"url",children:[(0,s.jsx)(n.a,{href:"https://api.hivekit.io/v2/realm/",children:"https://api.hivekit.io/v2/realm/"}),(0,s.jsx)("i",{children:"[realmId]"}),"/object/",(0,s.jsx)("i",{children:"[objectId]"})]})]}),"\n",(0,s.jsx)(n.p,{children:"Creates a new object or updates an existing one."}),"\n",(0,s.jsx)(n.admonition,{type:"tip",children:(0,s.jsxs)(n.p,{children:["If you are using IDs with slashes, (e.g. ",(0,s.jsx)(n.code,{children:"scooter/14"}),") as part of ",(0,s.jsx)(n.a,{href:"/guides/core/core-concepts#ids--id-patterns",children:"Hivekit's ID pattern functionality"}),", make sure to ",(0,s.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent",children:"URL encode"})," them before passing them to the API via the URL."]})}),"\n",(0,s.jsx)(n.h4,{id:"request-body",children:"Request Body"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{ \r\n "label": "Scooter #14", // optional\r\n "location": {\r\n "longitude": 12.345, // required longitude in degree\r\n "latitude": 12.345, // required latitude in degree\r\n "altitude": 230, // optional altitude in meters above NN\r\n "speed": 5, // optional speed in m/s\r\n "heading": 90, // optional heading in degree\r\n "accuracy": 6, // optional location accuracy in meters\r\n "altitudeAccuracy": 7, // optional altitude accuracy in meters\r\n "time": "2021-01-01T12:00:00Z" // optional time of location, expressed as RFC3339Nano\r\n }\r\n "data": { // optional\r\n "charge": 0.7,\r\n }\r\n}\n'})}),"\n",(0,s.jsx)(n.h4,{id:"response-body",children:"Response Body"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\r\n "result": "success"\r\n}\n'})}),"\n",(0,s.jsx)(n.h3,{id:"create-or-update-objects-in-bulk",children:"Create or Update Objects in Bulk"}),"\n",(0,s.jsxs)("div",{class:"rest-api-header",children:[(0,s.jsx)("span",{class:"post method",children:"POST"}),(0,s.jsxs)("span",{class:"url",children:[(0,s.jsx)(n.a,{href:"https://api.hivekit.io/v2/realm/",children:"https://api.hivekit.io/v2/realm/"}),(0,s.jsx)("i",{children:"[realmId]"}),"/object"]})]}),"\n",(0,s.jsx)(n.p,{children:"Creates or updates multiple objects at once. You can also use this endpoint to upload the location history for a single object."}),"\n",(0,s.jsx)(n.admonition,{type:"tip",children:(0,s.jsxs)(n.p,{children:["If you are using IDs with slashes, (e.g. ",(0,s.jsx)(n.code,{children:"scooter/14"}),") as part of ",(0,s.jsx)(n.a,{href:"/guides/core/core-concepts#ids--id-patterns",children:"Hivekit's ID pattern functionality"}),", make sure to ",(0,s.jsx)(n.a,{href:"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent",children:"URL encode"})," them before passing them to the API via the URL."]})}),"\n",(0,s.jsx)(n.h4,{id:"request-body-1",children:"Request Body"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{"objects": [{ \r\n "id": "scooter/14", // required\r\n "label": "Scooter #14", // optional\r\n "location": {\r\n "longitude": 12.345, // required longitude in degree\r\n "latitude": 12.345, // required latitude in degree\r\n "altitude": 230, // optional altitude in meters above NN\r\n "speed": 5, // optional speed in m/s\r\n "heading": 90, // optional heading in degree\r\n "accuracy": 6, // optional location accuracy in meters\r\n "altitudeAccuracy": 7, // optional altitude accuracy in meters\r\n "time": "2021-01-01T12:00:00Z" // optional time of location, expressed as RFC3339Nano\r\n },\r\n "data": { // optional\r\n "charge": 0.7,\r\n }\r\n},{ \r\n "id": "scooter/15", // required\r\n // you can also include partial updates. In this case, only the specified fields will be updated\r\n "location": {\r\n "longitude": 12.345, // longitude in degree\r\n "latitude": 12.345, // latitude in degree\r\n },\r\n}]}\n'})}),"\n",(0,s.jsx)(n.h4,{id:"response-body-1",children:"Response Body"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\r\n "result": "success"\r\n}\n'})}),"\n",(0,s.jsx)(n.h3,{id:"read-an-object",children:"Read an Object"}),"\n",(0,s.jsxs)("div",{class:"rest-api-header",children:[(0,s.jsx)("span",{class:"get method",children:"GET"}),(0,s.jsxs)("span",{class:"url",children:[(0,s.jsx)(n.a,{href:"https://api.hivekit.io/v2/realm/",children:"https://api.hivekit.io/v2/realm/"}),(0,s.jsx)("i",{children:"[realmId]"}),"/object/",(0,s.jsx)("i",{children:"[objectId]"})]})]}),"\n",(0,s.jsx)(n.h4,{id:"response-body-2",children:"Response Body"}),"\n",(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\r\n "id": "scooter/14",\r\n "label": "Scooter #14",\r\n "location": {\r\n "longitude": 12.345,\r\n "latitude": 12.345,\r\n "altitude": 230,\r\n "speed": 5,\r\n "heading": 90,\r\n "accuracy": 6,\r\n "altitudeAccuracy": 7,\r\n "time": "2021-01-01T12:00:00Z"\r\n },\r\n "data": {\r\n "charge": 0.7\r\n }\r\n}\n'})}),"\n",(0,s.jsx)(n.h3,{id:"list-objects",children:"List Objects"}),"\n",(0,s.jsxs)("div",{class:"rest-api-header",children:[(0,s.jsx)("span",{class:"get method",children:"GET"}),(0,s.jsxs)("span",{class:"url",children:[(0,s.jsx)(n.a,{href:"https://api.hivekit.io/v2/realm/",children:"https://api.hivekit.io/v2/realm/"}),(0,s.jsx)("i",{children:"[realmId]"}),"/object?fields=",(0,s.jsx)("i",{children:"charge"}),"&filter=",(0,s.jsx)("i",{children:"charge>0.5"}),"&shape=",(0,s.jsx)("i",{children:'{"cx":56.78,"cy":14.109 ,"r": 10000}'})]})]}),"\n",(0,s.jsxs)(n.p,{children:["Lists the objects within a given realm. The list can be filtered based on multiple criteria using the ",(0,s.jsx)(n.code,{children:"filter"})," parameter and restricted to certain bounds using ",(0,s.jsx)(n.code,{children:"shape"}),". You can also include additional fields from the object's data in the response using the ",(0,s.jsx)(n.code,{children:"fields"})," parameter."]}),"\n",(0,s.jsxs)(n.admonition,{type:"tip",children:[(0,s.jsxs)(n.p,{children:["If you are looking for a way to fulltext-search for objects instead, have a look at ",(0,s.jsx)(n.a,{href:"/docs/http-api/realm#search-within-a-realm",children:"the realm/search endpoint"}),"."]}),(0,s.jsx)(n.h4,{id:"query-parameters",children:"Query parameters"}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"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."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"filter"})," (optional): ",(0,s.jsx)(n.a,{href:"/guides/core/core-concepts#attribute-selectors",children:"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 ",(0,s.jsx)(n.code,{children:"="}),", ",(0,s.jsx)(n.code,{children:"!="}),", ",(0,s.jsx)(n.code,{children:">"}),", ",(0,s.jsx)(n.code,{children:"<"}),". The value can be a string, number, boolean, or null. The conditions are combined using the logical operator ",(0,s.jsx)(n.code,{children:"and"}),". The filter expression is case-sensitive."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"shape"})," (optional): A ",(0,s.jsx)(n.a,{href:"/docs/js-client-sdk/realm-area#shape-data-structure",children:"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:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Circle"}),": ",(0,s.jsx)(n.code,{children:'{"cx":<longitude>,"cy":<latitude>,"r":<radius in meter>}'})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Rectangle"}),": ",(0,s.jsx)(n.code,{children:'{"w":<longitude>,"n":<latitude>,"e":<longitude>,"s":<latitude>}'})]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Polygon"}),": ",(0,s.jsx)(n.code,{children:'{"points":[[<longitude>,<latitude>],...]}'})]}),"\n"]}),"\n"]}),"\n"]}),(0,s.jsx)(n.h4,{id:"response-body-3",children:"Response Body"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\r\n "scooter/14": {\r\n "id": "scooter/14",\r\n "label": "Scooter 14",\r\n "data": {\r\n "charge": 0.2\r\n },\r\n "connectionStatus": "dis"\r\n },\r\n "scooter/17": {\r\n "id": "scooter/17",\r\n "label": "Scooter 17",\r\n "data": {\r\n "charge": 0.7\r\n },\r\n "connectionStatus": "dis"\r\n }\r\n}\n'})}),(0,s.jsx)(n.h4,{id:"examples",children:"Examples"}),(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm: ",(0,s.jsx)(n.code,{children:"GET https://api.hivekit.io/v2/realm/123/object"})]}),"\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm and include their charge level and riderId: ",(0,s.jsx)(n.code,{children:"GET https://api.hivekit.io/v2/realm/123/object?fields=charge,riderId"})]}),"\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm with a charge level above 50% that currently have a rider: ",(0,s.jsx)(n.code,{children:"GET https://api.hivekit.io/v2/realm/123/object?filter=charge>0.5,riderId!=null"})]}),"\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm that are within a 10km radius of a given point: ",(0,s.jsx)(n.code,{children:'GET https://api.hivekit.io/v2/realm/123/object?shape={"cx":56.78,"cy":14.109,"r":10000}'})]}),"\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm that are within a given polygon: ",(0,s.jsx)(n.code,{children:'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]]}'})]}),"\n",(0,s.jsxs)(n.li,{children:["List all objects in a realm that are within a given rectangle: ",(0,s.jsx)(n.code,{children:'GET https://api.hivekit.io/v2/realm/123/object?shape={"w":56.78,"n":14.109,"e":56.88,"s":14.119}'})]}),"\n"]}),(0,s.jsx)(n.h3,{id:"delete-an-object",children:"Delete an Object"}),(0,s.jsxs)("div",{class:"rest-api-header",children:[(0,s.jsx)("span",{class:"delete method",children:"DELETE"}),(0,s.jsxs)("span",{class:"url",children:[(0,s.jsx)(n.a,{href:"https://api.hivekit.io/v2/realm/",children:"https://api.hivekit.io/v2/realm/"}),(0,s.jsx)("i",{children:"[realmId]"}),"/object/",(0,s.jsx)("i",{children:"[objectId]"})]})]}),(0,s.jsx)(n.h4,{id:"response-body-4",children:"Response Body"}),(0,s.jsx)(n.pre,{children:(0,s.jsx)(n.code,{className:"language-json",children:'{\r\n "result": "success"\r\n}\n'})})]})]})}function h(e={}){const{wrapper:n}={...(0,t.a)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(d,{...e})}):d(e)}},1151:(e,n,i)=>{i.d(n,{Z:()=>o,a:()=>a});var s=i(7294);const t={},r=s.createContext(t);function a(e){const n=s.useContext(r);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:a(e.components),s.createElement(r.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.