Pointerra REST API Reference

This document outlines the general principles of the Pointerra REST API. Detailed reference information on the current API endpoints can be found here.

Introduction

The Pointerra API is designed around the principles of RESTful APIs. The API has resource-oriented URLs, and uses HTTP response codes to indicate API errors. The API supports CORS, so you can use the API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

Authentication

All requests to API endpoints must include your secret API authentication token in the Authorization header of the request. You can get your API token from your Profile page. Your API token authenticates your access to resources - do not embed your secret API token in any publicly accessible code (e.g. client-side code). Typically this means you should only make calls to the Pointerra API from your server-side code.

Use "Authorization": "Token <your_token>" in request headers for any API call.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

HTTP response codes are used to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, and invalid pointcloud id was used), and codes in the 5xx range indicate an internal error with the Pointerra service.

For failures, the detail field of the response will contain some information on why the request failed. For example, if credentials are not valid the response will be a 401 and contain -

 
x
HTTP 401 UNAUTHOURIZED
{
    "detail": "Invalid token."
}

API Request Rate Limits

There is rate limiting on the API requests for the Pointerra service - this is a per-token limit and is currently set at 60 requests per minute. When an application exceeds the rate limit for a given API endpoint, the API will return a 429 "Too Many Requests" error response.

Pagination

All top-level API resources have support for fetches via "list" API methods. For instance a common usage would be to get a list of pointclouds. All list API methods share a common pagination structure, based on page sizes and page numbers.

This pagination style accepts per_page and page values in the request query parameters to control the range of returned values from the collection. The default value for per_page is generally 10. The page parameter defaults to 1. So a request without these parameters would return the first 10 items (or less if there are not 10 items to return).

Example Request:

 
xxxxxxxxxx
GET https://app.pointerra.io/api/pointclouds?per_page=50&page=2

Example Response

 
xxxxxxxxxx
HTTP 200 OK
{
    "total": 168,
    "per_page": 50,
    "current_page": 2,
    "last_page": 4,
    "next_page_url": "https://app.pointerra.io/api/pointclouds/?page=3",
    "previous_page_url": "https://app.pointerra.io/api/pointclouds/?page=1",
    "from": 51,
    "to": 100,
    "data": [
      ...
     ]
}

Note that previous_page_url or next_page_url will be null if the current response is already at the first or last page of the collection. Use response.data to access the array of the objects within the page returned by the request.

For performance reasons, there is no way to guarantee returning of the entire collection. While you can make the per_page parameter large, you must always ensure your code is designed to deal with a paginated response, and hence have to make multiple requests to get the entire collection.

Standard GET Request Query Parameters for Collections

Most GET requests will support the following query parameters in the URL. Each collection may also support additional filtering options that are specific to the collection. These are documented separately with each collection.

Parameter	Type	Meaning
fields	list (comma separated string)	Used to limit the fields in a response object; fields not listed will not be returned. Separate multiple fields with commas. Note that by default, if fields is not specified, each collection will return what it thinks is the most useful set of commonly required fields. If you want all available fields to be returned, specify fields=all
omit	list (comma separated string)	The opposite of fields. Removes the specified fields from the response object.
search	string	Free text search term used to limit returned values. Which fields in the data are searched will be depended on the collection.
sort	string (field name)	Specify which field you want to sort the paginated response on. Use a minus sign to reverse sort order (e.g sort=-name for reverse alpha)

Example Request

 
xxxxxxxxxx
GET https://app.pointerra.io/api/pointclouds?fields=pointcloud_id,name&sort=name

Full API Reference

Reference information for each top level API collection can be found here. Note that you will only be able to see API endpoints that your login credentials allow when using this page.

Common API Usage Examples

Below are some common examples (with dummy data) of the types of requests that can be made. In real code, you will need to add pagination and filtering/sorting as required.

Get a list of pointclouds

Get a list of pointclouds that the API token has access to, sorted by name.

 
xxxxxxxxxx
GET https://app.pointerra.io/api/pointclouds?fields=pointcloud_id,name,num_points&sort=name

Example Response

 
x
HTTP 200 OK
{
    "total": 168,
    "per_page": 10,
    "current_page": 1,
    "last_page": 17,
    "next_page_url": "https://app.pointerra.io/api/pointclouds/?fields=pointcloud_id,name,num_points&page=2",
    "previous_page_url": null,
    "from": 1,
    "to": 10,
    "data": [
        {
            "pointcloud_id": "abcdef12-e5e9-4e1f-b2c0-166e6f10785f",
            "name": "example 1",
            "num_points": 1076595559
        },
        {
            "pointcloud_id": "abcdef12-8a54-40a6-9c3c-a993d386d36f",
            "name": "example 2",
            "num_points": 564029518
        },
        {
            "pointcloud_id": "abcdef12-9c5f-46cb-89da-989d904e46d3",
            "name": "example 3",
            "num_points": 14723776
        },
        {
            "pointcloud_id": "abcdef12-2202-4eb2-a28f-411441e3ce79",
            "name": "example 4",
            "num_points": 178714335
        },
        {
            "pointcloud_id": "abcdef12-6f76-4b30-b2bc-d354274ddbc9",
            "name": "example 5",
            "num_points": 80495130
        },
        {
            "pointcloud_id": "abcdef12-cf1a-48d9-8ee2-d7e2c4e51c75",
            "name": "example 6",
            "num_points": 422868202
        },
        {
            "pointcloud_id": "abcdef12-71e5-4d70-b39c-d4de30809f06",
            "name": "example 7",
            "num_points": 388981748
        },
        {
            "pointcloud_id": "abcdef12-8ac8-4c1f-a866-dc85ba33be5a",
            "name": "example 8",
            "num_points": 1420972855
        },
        {
            "pointcloud_id": "abcdef12-f226-4e6d-ab22-946098493a7e",
            "name": "example 9",
            "num_points": 449418216
        },
        {
            "pointcloud_id": "abcdef12-1bd4-4f63-8de1-60e1800fbafc",
            "name": "example 10",
            "num_points": 23782456
        }
    ]
}

Get details for a particular pointcloud

Get detailed information for a specified pointcloud (looked up by id). Note that since this is not returning a collection, the response will not be paginated. In this case, the default fields are returned as no fields query parameter was supplied. For performance/bandwidth reasons, you will generally want to limit the returned object to only include the fields you require.

 
x
GET https://app.pointerra.io/api/pointclouds/abcdef12-1bd4-4f63-8de1-60e1800fbafc

Example Response

 
x
HTTP 200 OK
{
    "pointcloud_id": "abcdef12-1bd4-4f63-8de1-60e1800fbafc",
    "name": "example 10",
    "public": false,
    "is_active": true,
    "owner": 57,
    "owner_details": {
        "name": "ACME",
        "slug": "acme",
        "company_id": "abcdef12-e98d-45db-9f0c-1a874f905e4c"
    },
    "bounds_llh_tuple": [
        [
            119.165430460077,
            20.3043164373924,
            7.77819772507056
        ],
        [
            119.165702911792,
            20.3047275893521,
            18.4180960836089
        ]
    ],
    "created": "2017-06-04T09:14:21.594068Z",
    "modified": "2017-07-04T10:15:11.165593Z",
    "num_points": 23782456,
    "intensity_range": {
        "max": 2047,
        "min": 0
    },
    "colour_range": {
        "max": {
            "b": 0,
            "r": 0,
            "g": 0
        },
        "min": {
            "b": 255,
            "r": 255,
            "g": 255
        }
    },
    "resolution": 0.001,
    "source_srs": "proj4:+proj=tmerc +lat_0=22.31213333333334 +lon_0=114.1785555555556 +k=1 +x_0=836694.05 +y_0=819069.8 +ellps=intl +towgs84=-162.619,-276.959,-161.764,0.067753,-2.243649,-1.158827,-1.094246 +units=m +no_defs  +vto_meter=1.0",
    "friendly_srs": "Hong Kong 1980 Grid System",
    "has_srs": true,
    "absolute_url": "/pointclouds/example10/",
    "source_vertical_datum": "geoid",
    "classification_list": "",
    "size_on_disk": 82116850
}