ePlant's REST API provides access to Tree Tag telemetry and metadata. Our API accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.
\nAuthentication to the API is performed via tokens, utilizing OAuth 2.0 flows. Users retrieve tokens by submitting their credentials to the authorization endpoint. The response contains several keypairs, including the AccessToken. That token value should be included in the header of subsequent requests to all other endpoints, with the following syntax:
\"Authorization\": \"Bearer {AccessTokenValue}\"\n\nThe metadata APIs paginate results from requests to the endpoints. With pagination, the responses are divided into \"pages\" of data that are 5 MB in size (or less). A client can process the first page of results, then the second page, and so on. A single request only returns a result set that fits within the 5 MB size limit. To determine whether there are more results, and to retrieve them one page at a time, clients should do the following:
\nstopIndex key in the result, there are no more items to be retrieved.stopIndex key, construct a new request, using the stopIndex value from step 1 and as the startIndex parameter in the new request.In other words, the stopIndex from a response should be used as the startIndex for the next request. If there is not a stopIndex element in a response, then you have retrieved the final page of results.
Device Data Request and Plant Data Request endpoints limit the size of the requested data. Requests should be constrained to the equivalent of 45 days worth of data for a single Tree Tag operating at a 5 minute sample rate.
\nRequests are time-bounded, and the maximum allowable timespan (in days) for a request can be calculated as:
\ntimespan = (45 days * sample rate) / (Tree Tag Qty * 5)
\nWhen calculating the timespan for the Plant Data Request endpoint, the number of Tree Tags on the plant must first be determined by the user (via the Association Metadata Request endpoint).
\nePlant's API is a shared resource between all API users. Please limit requests to the following following rate limits:
\nUsername, Password, and Client Id values are provided by ePlant.
\nAccessToken: token to be submitted in the header of requests to all other endpoints
\nExpiresIn: token timeout (seconds)
\nIdToken
\nRefreshToken
\nTokenType
\n","urlObject":{"protocol":"https","host":["cognito-idp","us-west-2","amazonaws","com"],"query":[],"variable":[]}},"response":[{"id":"53c33b78-c0ef-4120-9f1f-3469fda558ff","name":"200 OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/x-amz-json-1.1","type":"text"},{"key":"X-Amz-Target","value":"AWSCognitoIdentityProviderService.InitiateAuth","type":"text"}],"body":{"mode":"raw","raw":"{\n \"AuthParameters\": {\n \"USERNAME\": \"email@test.com\",\n \"PASSWORD\": \"password123\"\n },\n \"AuthFlow\": \"USER_PASSWORD_AUTH\",\n \"ClientId\": \"clientId123\"\n }","options":{"raw":{"language":"json"}}},"url":"https://cognito-idp.us-west-2.amazonaws.com"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","name":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"AuthenticationResult\": {\n \"AccessToken\": \"eyasdnfaosdnf23424nn42n42i4n2...\",\n \"ExpiresIn\": 21600,\n \"IdToken\": \"eyJasdfnosnf234n242n4i24n242n2...\",\n \"RefreshToken\": \"eyJs246n66n7432n42n64...\",\n \"TokenType\": \"Bearer\"\n },\n \"ChallengeParameters\": {}\n}"},{"id":"240fc423-d89d-45d2-8062-4b97c0cc07c1","name":"400 User Not Found","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/x-amz-json-1.1","type":"text"},{"key":"X-Amz-Target","value":"AWSCognitoIdentityProviderService.InitiateAuth","type":"text"}],"body":{"mode":"raw","raw":"{\n \"AuthParameters\": {\n \"USERNAME\": \"email@test.com\",\n \"PASSWORD\": \"password123\"\n },\n \"AuthFlow\": \"USER_PASSWORD_AUTH\",\n \"ClientId\": \"clientId123\"\n }","options":{"raw":{"language":"json"}}},"url":"https://cognito-idp.us-west-2.amazonaws.com"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 10 Feb 2023 19:18:05 GMT"},{"key":"Content-Type","value":"application/x-amz-json-1.1"},{"key":"Content-Length","value":"67"},{"key":"Connection","value":"keep-alive"},{"key":"x-amzn-RequestId","value":"a773055c-8a94-4da2-9eef-a95665ce6ea1"},{"key":"x-amzn-ErrorType","value":"UserNotFoundException:"},{"key":"x-amzn-ErrorMessage","value":"User does not exist."}],"cookie":[],"responseTime":null,"body":"{\n \"__type\": \"UserNotFoundException\",\n \"message\": \"User does not exist.\"\n}"}],"_postman_id":"7ac0ce80-0eea-42d2-83e3-02200314f7c5"},{"name":"Device Metadata Request","event":[{"listen":"test","script":{"id":"f187a1aa-4e25-40c7-aef2-6d4883cb718d","exec":["pm.test(\"Status code matches expected\", function () {"," pm.response.to.have.status(pm.iterationData.get(\"statusCode\"));","});","","pm.test(\"Expected error message returned\", function () {"," var jsonData = pm.response.json();"," pm.expect(pm.response.text()).to.include(pm.iterationData.get(\"errorMessage\"));","});"],"type":"text/javascript"}}],"id":"cc4ae438-c7b9-4ba9-9f10-a34fc5c04828","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{Bearertimestamp: UTC
\nserial number: Tree Tag serial number
\ndev eui: Tree Tag DevEUI
\nfirmware version: Tree Tag firmware version
\ninteraction type: NFC Interaction type - Active/Deactivate/Scan
\nlatitude
\nlongitude
\nowner: Mobile app user
\ndendrometer: Dendrometer measurement (microns)
\ntemperature: Temperature measurement (0.1 degC)
\nhumidity: Relative Humidity measurement (%)
\nlight: Solar panel Voc (mV)
\nlean angle: Tree Tag orientation parameter 1, 0-18000 (0.01 degrees)
\nlean direction: Tree Tag orientation parameter 2, 0-360 (degrees)
\nsystem voltage: Tree Tag power status (V)
\nmag x: Magnetomer x-axis measurement
\nmag y: Magnetomer y-axis measurement
\nmag z: Magnetomer z-axis measurement
\npost result: Power On Self Test (POST) result. Non-zero result indicates the device may be in an unreliable state.
\nradio state: Wireless network radio state
\nsampling state: Sampling state
\nlast sample time: Last sample timestamp
\nlast uplink state: Wireless network uplink state
\nlast uplink time: Wireless network uplink time
\nlast uplink spread factor: Wireless network uplink spread factor
\nlast uplink power: Wireless network uplink power (dBm)
\nlast uplink dr: Wireless network uplink data rate
\nlast received snr: Wireless network downlink signal-to-noise ratio
\nlast received rssi: Wireless network downlink RSSI
\nlast join time: Wireless network join timestamp
\nsample time: Time sample was collected (UTC)
\nreceived time: Time data was received in the cloud (UTC)
\ndendrometer: Dendrometer measurement (microns)
\ntemperature: Air temperature measurement (degC)
\nhumidity: Relative Humidity measurement (%)
\nlight: Incident radiance (W/m^2)
\nsystem voltage: Tree Tag power status (V)
\nlean angle: Tree Tag orientation parameter 1 (degrees)
\nlean direction: Tree Tag orientation parameter 2 (degrees)
\nsample time: Time sample was collected (UTC)
\nreceived time: Time data was received in the cloud (UTC)
\nserial number: Tree Tag serial number
\ndendrometer: Dendrometer measurement (microns)
\ntemperature: Air temperature measurement (degC)
\nhumidity: Relative Humidity measurement (%)
\nlight: Incident radiance (W/m^2)
\nsystem voltage: Tree Tag power status (V)
\nlean angle: Tree Tag orientation parameter 1 (degrees)
\nlean direction: Tree Tag orientation parameter 2 (degrees)
\n