PIX4Dinspect API Documentation

Download OpenAPI specification:Download

Authentication

OAuth2

Pix4Dinspect API authentication procedure

This document describes how to get started with the Pix4D Inspect REST API, which provides third party applications access to the Pix4Dinspect API service. It allows a Pix4D Inspect client to access his/her data on the cloud and perform a range of operations on them.

  • For end to end security, HTTPS is used in all the APIs
  • The base URL for API endpoints is: https://api.inspect.pix4d.com
  • Each REST API call needs to be authenticated. See Authentication below
  • The communication format is expected to be JSON, unless otherwise stated

Getting access to Pix4Dinspect REST API

To register the application and start using the REST API you will need to acquire a Pix4Dinspect license. Please contact us at Salesteam (at) pix4d.com and we'll help you get set up and will give you an api key that represent your application, the one that will connect to the Pix4DinspectAPI and that you will use to authenticate to the API.

Note that the api key as an identifier for the client application should be handled securely.

API Authentication

Equipped with the Inspect api key, the first step is to retrieve an authentication jwt token. An authentication token identifies both the application connecting to the API and the Inspect user this application is connecting on behalf of.

The jwt token and the api key must be passed along every single request that the application makes to the Pix4D Inspect API. They are passed in the HTTP Authorization header, like so:

Authorization: Bearer <INSPECT_JWT_TOKEN>
X-Api-Key: <API_KEY>

Client Credentials flow

Using this flow, an API client application can get access to its own Inspect user account (and only to that account). With this method, the authentication is straightforward and only requires the applications' user/password pair.

The client must send the following HTTP POST request to https://inspect.pix4d.com/v1/auth/token/ with a payload containing:

  • username: the email account of the account
  • password: the password of the account

And a header containing:

  • x-api-key: the api-key that identifies the account

example:

curl -X POST \
  -d "username=company@pix4d.com&password=YuB7fu…" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  https://inspect.pix4d.com/v1/auth/token/

Token information

Token content

The response you receive when performing the authentication request above has the following content (In JSON):

  • api_token: the token value that you will have to join in all your requests
  • expires_in: the number of seconds the token is valid for. After this number of seconds, API requests using this token will get rejected and you will need to request a new token through the authentication procedure again
{
  "api_token": "<ACCESS_TOKEN>",
  "expires_in": 36000
}

Refreshing the token

When the token expires, you simply need to perform the above authentication procedure again to get a fresh token.

Using the API

For an in-depth description of all possible API commands, please refer to the API documentation. This documentation is only available for users who already have an API access.

Security Scheme Type OAuth2
Client Credentials OAuth Flow
Scopes:
  • cloud:read -

    Grant read access

  • cloud:write -

    Grant write access

First Example

In this guide, you will discover how to get a token, upload a new inspection, get it processed, and access the results.

This same tutorial is available here as a Jupyter notebook, for the users that prefer to follow a Python implementation.

IMPORTANT: To follow this tutorial it is necessary to have at least one resource of the type Projects in the account and one of the type Tower inventory if you select the detect_antennas option for the processing. To know more about allowance please read the allowance guide.

Prerequisites

API Access

You need a Pix4Dinspect license to authenticate and get an access to the API. Please contact your Pix4D reseller to start a trial if you don't have a license already. More information is available on Pix4D Inspect on our product page.

With this license comes your authentication information, your username, password and api-key which are the values you need in this guide.

Terminal tooling

This guide can be completed from the Terminal, using basic tooling:

  • curl command line is used to call the API, it should be included in your OS or docker image.
  • aws-cli is used to upload and download the data, you can get it directly from AWS: https://aws.amazon.com/cli/

Photos to process

We will use a set of photos to be processed in this guide. If you don't have a good dataset at your disposal, feel free to download one of our sample datasets, for example the demo dataset. We consider your are unzipping the archive in ./photos in this guide.

Authenticate

We are using OAuth2 Client Credientials flow to generate an api token. Using the Username, Password and Api-Key provided with your Pix4Dinspect license, you can get an Api Token using the following curl command:

export INSPECT_USERNAME=__YOUR_USERNAME__
export INSPECT_PASSWORD=__YOUR_PASSWORD__
export INSPECT_API_KEY=__YOUR_API_KEY__
curl --request POST \
  --url https://inspect.pix4d.com/v1/auth/token/ \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --form username=$INSPECT_USERNAME \
  --form password=$INSPECT_PASSWORD

The response body is a JSON document containing an api_token attribute:

{
  "api_token": "<INSPECT_JWT_TOKEN>",
  "expires_in": 172800,
}

For the following example we will reference the token as INSPECT_JWT_TOKEN

export INSPECT_JWT_TOKEN=__INSPECT_JWT_TOKEN__

You can learn more about authentication in the reference documentation (see Authentication).

Create a new asset

Let's start by creating an asset. The only required parameters are the asset name and the asset type, the rest are optional. The list of available asset types and their ids are included in the reference documentation (see Asset creation).

All of the parameters can be passed as a JSON payload in the request body.

curl --request POST \
  --url https://inspect.pix4d.com/v1/assets/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"name": "Demo Cell Tower", "type": 1}'

Create your first inspection

Once having an asset, it's possible to create an inspection. To do this, we only need as mandatory fields the id of the asset created before and the processing parameters choosen for the inspection. The additional fields you can include in the inspection are included in the reference documentation (see Inspection creation).

As in the previous step, the parameters can be passed as a JSON payload in the request body.

Since this json can be too long, you can store it in a json file inside your working directory as inspection.json and reference it later with curl.

    {
      "asset": 0,
      "processing_parameters": {
        "is_video": false,
        "generate_point_cloud": true,
        "clip_point_cloud": true,
        "clipping_radius": 0,
        "detect_antennas": true
      }
    }
curl --request POST \
  --url https://inspect.pix4d.com/v1/inspections/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @inspection.json

The response will be a 201 CREATED and the response body will include the inspection details. It can be usefull to add the inspection id as an enviroment variable during this tutorial.

export INSPECTION_ID=<THE INSPECTION ID>

Upload the photos

It is recommended to use the shell AWS CLI or the python boto3 library but other tools can work as well. First, we need to retrieve the AWS S3 credentials associated with this inspection:

curl --url https://inspect.pix4d.com/v1/inspections/$INSPECTION_ID/s3_credentials/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

The answer contains all the S3 information we need, at least the access_key, secret_key and the session_token.

{
  "access_key": "ASIATOCJLBKSU2CVJIHR",
  "secret_key": "5OGGBSvn8Sesdu8l...<remainder of the secret key>",
  "session_token": "FwoGZXIvYX...<remainder of security token>",
  "expiration": "2021-05-10T21:55:47Z",
  "bucket": "prod-pix4d-cloud-default",
  "key": "user-199a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349",
  "server_time": "2021-05-19T09:55:47.357641+00:00",
  "region": "us-east-1"
}

We can store the S3 credentials in our environment, so that they will get picked up by the AWS CLI tool.

export AWS_ACCESS_KEY_ID=ASIATOCJLBKSU2CVJIHR
export AWS_SECRET_ACCESS_KEY='5OGGBSvn8Sesdu8l...<remainder of the secret key>'
export AWS_SESSION_TOKEN='AQoDYXdzEJr...<remainder of security token>'
export S3_BUCKET=prod-pix4d-cloud-default
export S3_BASE_PATH='user-199a56ab-7ac6-d6d1-4778-5b4d338fc9de/project-883349'

Make sure to prefix all your desired destination locations with the path returned in the credentials call. This is the only place for which write access is granted. Make sure that the files are proper images and their names include an extension supported by Pix4Dinspect.

Provided your images are located in a folder located at $HOME/images, and that it contains only images, you can run the command:

aws s3 cp ./photos/ "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

If your folder contains multiple images, you need to copy them one by one, likely using a script.

aws s3 cp $HOME/images/DJI_0389.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0390.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0391.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0392.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0393.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive
aws s3 cp $HOME/images/DJI_0394.JPG "s3://${S3_BUCKET}/${S3_BASE_PATH}/" --recursive

Then you need to register the images in the Pix4D Inspect API so that they will be processed. It is possible to upload files that are not inspection inputs, and it is not possible to know which files are meant as input. It is therefore required to register each S3 uploaded file in the API. Register the uploaded files you uploaded (single API call for less than 500 images):

curl --request POST --url https://inspect.pix4d.com/v1/inspections/$INSPECTION_ID/register_images/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "{
      \"image_keys\": [
        \"${S3_BASE_PATH}//DJI_0389.JPG\",
        \"${S3_BASE_PATH}//DJI_0390.JPG\",
        \"${S3_BASE_PATH}//DJI_0391.JPG\",
        \"${S3_BASE_PATH}//DJI_0392.JPG\",
        \"${S3_BASE_PATH}//DJI_0393.JPG\",
        \"${S3_BASE_PATH}//DJI_0394.JPG\"
      ]
    }"

The response should confirm that the various images have been registered amongst other data.

{ "nb_images_registered": 10 }

Start processing

You are now ready to start processing your inspection:

curl --request POST --url https://inspect.pix4d.com/v1/inspections/$INSPECTION_ID/process/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

IMPORTANT: The allowance resources will be consumed when starting the processing of an inspection. Not before, not after.

Check the processing state

curl --url https://inspect.pix4d.com/v1/inspections/$INSPECTION_ID/ \
  --header "Authorization: Bearer ${INSPECT_JWT_TOKEN}" \
  --header "X-Api-Key": ${INSPECT_API_KEY}" \
  --header "Content-Type: application/json"

A response can look like:

{
    "id": 1417,
    "project_id": 745411,
    "can_retry": false,
    "retry_of": null,
    "retries": [],
    "asset": {
        "id": 915,
        "name": "Demo Cell Tower",
        "type": 1,
        "latitude": "4.02012900",
        "longitude": "9.80536800",
        "description": "Demo asset for a cell tower",
        "created_at": "2020-09-17T17:09:42.289903+02:00",
        "updated_at": "2021-06-01T17:07:48.447830+02:00"
    },
    "status": {
        "id": 7,
        "name": "Processing completed"
    },
    "pcs_task_uuid": "bcdbf959-be66-4595-bcea-35879d5370d5",
    "inspection_date": "2020-09-17T17:09:43.116225+02:00",
    "annotations": [],
    "description": "Demo inspection",
    "name": "My first inspection",
    "is_main": true,
    "ground_reference_altitude": "12.6383",
    "processing_parameters": null,
    "report_status": "available",
    "created_at": "2020-09-17T17:09:43.116225+02:00",
    "updated_at": "2021-06-15T15:20:39.576966+02:00"
}

Once the status changes to Processing completed, the inspection's main outputs are ready to be retrieved.

Once the inspection is processed, it is possible to access to the visualization page through a browser, using the same credentials as in this tutorial (username and password). The URL should look like this: https://inspect.pix4d.com/project/<project_id>/

You can learn more about how to share your inspections in the reference documentation (see ShareTokens).