Tutorial: TreePlotter™ INVENTORY API

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.

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 developer’s 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

Detailed Developer Documentation and Testing API Calls on SwaggerHub

Security and Data Access

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/tpdemo

the API URL is

https://pg-cloud.com/api/tpdemo

A 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=testkey

The 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 at the bottom of the SwaggerHub page. The response includes fields, associated look up tables and user settings.

The API responses will contain the back end names of fields, and field values in the calls that connect to different layers in your TreePlotter application.

GET/{folder}/metadata/inventories/{inventory}
ex:
https://pg-cloud.com/api/tpdemo/metadata/inventories/tree

Understanding SwaggerHub API responses

• A successful API call will output three sections into the interface.
• The Snippets section will contain code snippets that are able to be copied out and used in your API integration code.
• The Code section will contain the status of the call along with response body, response headers, and the duration of the call.
• The Response section will contain your TreePlotter data.
• The SwaggerHub responses will include a geojson of the data you wished to call or a confirmation that the action was done.
• To extract out the API call you used for use in programming an API integration, click on the Snippet and the clipboard to copy out the curl and paste it into your code. Adjustments will have to be made for the appropriate coding language you are using.
• To call the next page, see the bottom of the response to your initial call. For large datasets, we recommend including supplemental pages in the API calls you make.

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.
• Customer Support will consult on the functionality of the API and assist in troubleshooting calls they are making. Note PlanIT Geo staff do not make API calls for customers or lead them through integrations