This document describes how to get started with the Pix4Dcloud REST API, which provides third party applications access to the Pix4Dcloud service. It allows a Pix4Dengine Cloud 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://cloud.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 Pix4Dcloud REST API
To register the application and start using the REST API you will need to acquire a Pix4Dengine Cloud license. Please contact us at Sales team (at) pix4d.com and we'll help you get set up and will give you a pair of client_id/client_secret that represent your application, the one that will connect to the Pix4D API and that you will use to authenticate to the API.
Note that as its name suggests, client_secret is a password identifying the client application and therefore should be handle securely.
API Authentication
Equipped with the Pix4D API client_id/client_secret, the first step is to retrieve an authentication token. An authentication token identifies both the application connecting to the API and the Pix4D user this application is connecting on behalf of.
This token must then be passed along every single request that the application makes to the Pix4D API. It is passed in the HTTP Authorization header, like so:
Authorization: Bearer <ACCESS_TOKEN>Pix4D Cloud REST API uses OAuth 2.0, the industry standard for connecting apps and accounts. OAuth 2.0 supports several "authentication flows" to retrieve an authentication token. Pix4D supports several of them that are each used for a specific purpose, but for Pix4D Engine Cloud customers, only one is relevant: "Client Credentials"
Client Credentials flow
Using this flow, an API client application can get access to its own Pix4D user account (and only to that account). With this method, the authentication is straightforward and only requires the applications' client_id/client_secret pair
The client must send the following HTTP POST request to https://cloud.pix4d.com/oauth2/token/ with a payload containing:
- grant_type: client_credentials
- client_id: the client ID of the application that was given to you by your Pix4D contact
- client_secret: the client_secret of the application that was given to you by your Pix4D contact
- token_format: jwt
example:
curl -X POST \
-d "grant_type=client_credentials&token_format=jwt&client_id=YuB7fu…&client_secret=GMSVvt8dF…" \
https://cloud.pix4d.com/oauth2/token/Token information
Token content
The response you receive when performing the authentication request above has the following content (In JSON):
- access_token: the token value that you will have to join in all your requests
- token_type: for Pix4D, this is always a Bearer token
- 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
- scope: describe what the token is valid for. In this case, it's always "read write" since you get a full access to your own account
{
"access_token": "<ACCESS_TOKEN>",
"token_type": "Bearer",
"expires_in": 36000,
"scope": "read write"
}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.
Hello,
We would like to use the functionality of calculate the volumen of respective zone in our web application.
For that reason, how can I generate a new token to access to your API of PIX4D Cloud?
Best Regards,
Lourdes (qAIRa)
This type of API functionality is reserved for users with an API license. This is not a feature available to a standard Pix4D cloud or Mapper license.
Hello,
How can I get an API license? How much it costs?