The TreePlotter™ INVENTORY API allows developers to interact programmatically with the data and features of TreePlotter. The API allows for two-way integration by pulling data from one software to be edited in another system and then returned to the original software.
Topics covered in this tutorial:
- Typical Use Cases
- Types of API Calls Available
- What TreePlotter Data is Accessible Through the API
- Security and Authorization
- Using the API
- Rate Limit Information
- Accessing Metadata
- Detailed Developer Documentation
Typical use cases for the API include developers using it to:
- Load data into Esri tools, QGIS, PowerBI, FME Software or another data analysis application.
- Display map features from INVENTORY in your own web app, mobile app, or desktop app.
- Create an integration with your existing system, such as a city asset management system.
Types of API Calls Available:
- GET: Which returns data.
- Require a folder name and layer name (if applicable)
- POST: Which adds a new feature to an inventory of data.
- Requires a data body in a JSON format.
- Point-type asset POST calls- require latitude and longitude
- Work Records POST calls require an asset_id, and layer_name
- PUT: Updates a specific data feature.
- Require a data body
- Require the PID of the feature the API user needs to update.
- DELETE: Deletes a feature given a primary ID.
What TreePlotter Data is Accessible Through the API
The TreePlotter INVENTORY API allows for extracting, updating, deleting, or creating new editable data from your TreePlotter application. There are some parameters within the calls to extract or edit a subset of data like Primary ID’s, Last Modified Dates, or Client Sites/Organizations. For the full developers documentation, scroll to the bottom of this page.
- Trees or other Inventory Layers
- Inspections
- Work Records
- Work Orders and Service Requests
- Metadata: Data Schemas, Field Names, Data Types and other database settings
Security and Data Access
- Authorize prior to the call by navigating to the lock icon on the right side of a call.
- Use a TreePlotter log in to access (basicauth).
- Enter your unique API key in the value section of the (apiKey).
- If the login or API key are incorrect you will receive a 401 error in the response body stating ‘Unauthorized’.
- If using another tool to make a call to the API, you must still use a basic authorization to make the call.
Using the API
The INVENTORY API is located at https://pg-cloud.com/api
For example, for the INVENTORY app at
https://pg-cloud.com/tpdemothe API URL is
https://pg-cloud.com/api/tpdemoA lowercase folder name and API key is required to access the API for your INVENTORY app. The key must be appended to the end of the query string on every call:
https://pg-cloud.website/api/tpdemo/wom/jobs?apiKey=testkeyThe API does require you use https, and URLs are case-sensitive
Rate Limit Information
All TreePlotter API endpoints (including WFS and REST services) use a rate limiter, with a rate limit of 5 requests per second, averaged over a 60 second window. Rate limiter information is included in the RateLimit HTTP response header.
If the rate limit is exceeded, further API requests will be returned with an HTTP 429 response code and a simple error message until the rate limiter resets. Your code will need to handle HTTP 429 responses and retry the original request a little later. We recommend you use an exponential backoff strategy.
Accessing Metadata to get all of the values for the look ups and fields
To decipher fields and field options of your inventory layers, a dictionary can be found in the metadata call. The response includes fields, associated look up tables and user settings.
GET/{folder}/metadata/inventories/{inventory}
ex:
https://pg-cloud.com/api/tpdemo/metadata/inventories/treeDetailed Developer Documentation and Testing API Calls
Known Limitations
- The API will output in a json format. For integrations with other systems, the outputted response will have to be programmed to fit into the other software requirements.
- Customers MUST enter the link all in lower case.