First you will need an API Key
More information is also available on our Data API.
Create a "Plan"
The Plan object is the central element to much of the DroneDeploy process. It is the container for all of the critical information about your map, and is required for many of the other operations you'll be performing with the API. Fortunately, setting up a plan with default values is easy.
POST /v2/plans
{
"name":"My Plan",
"geometry": [
{
"lat": 37.77217017379464,
"lng": -122.40822173862347
},
{
"lat": 37.77217017379464,
"lng": -122.40700387538845
},
{
"lat": 37.771335028907735,
"lng": -122.40700387538845
},
{
"lat": 37.771335028907735,
"lng": -122.40822173862347
}
],
"workflow": {
"job_type": "2d",
"quality": 9
}
}
curl -H "Content-Type: application/json" -X POST -d '{"folder_id": "1234013412340300", name":"My Plan", "workflow": {"job_type": "2d", "quality": 9}}' "https://public-api.dronedeploy.com/v2/plans?api_key={api_key}"
{
"id": "58b0490c95b03d000114a881"
}
-
folder_id: The id of the Project you would like to associate this Plan to. This is an optional field that allows you to create a Project for viewing within DroneDeploy.com. If you choose to not associate a Project ID, you will still be able to process map data and export, but you will be unable to see it on DroneDeploy.com. You can create a Project and get a folder_id via our GraphQL API. -
name: The name of your plan. It is best to name your plan something unique, although it is not required. Each plan is assigned a unique identifier within the DroneDeploy system. Defaults toAPI Generated Plan. -
job_type: Determines whether the map runs in Terrain ("2d") or Structures ("3d") mode, or if you're using an alternative processing mode such as 360 pano ("360_pano", or "walkthrough"). Defaults to"2d". -
quality: The processing quality of the map. Available values are3,6and9. A lower value means poorer quality, but much better processing speed. Defaults to9.
-
record_type: The type of the plan being created (map, pano, video, etc.). Available values are"map_plan","walkthrough_plan"and"progress_pano_360_plan". Defaults to"map_plan".
-
geometry: The area of the plan in the form of an array of latitude/longitude coordinates (see above code example). If a geometry is not specified, the processing area is determined by the source imagery itself. Defaults tonull. To create a valid geometry, here are some tips:- The lines of the polygon created by the geometry do not intersect itself. If you were to plot the coordinates in order (clockwise or counter-clockwise) with a line, the line should not cross itself.
- The polygon doesn't need to enclose itself (i.e., the last coordinate in the geometry is the same as the first coordinate in the geometry), but will still be valid if it does.
- Do not repeat coordinates.
Once a plan has been created, it is time to add some source imagery to the plan.
Create an "Image Transfer"
The Image Transfer object is the way API clients can indicate which source imagery should be used for a given plan. Once an image transfer object is created, the indicated URL is fetched and the photogrammetry process begins.
While an API client can specify a list of individual images for processing, it is a best practice to create a ZIP archive of all necessary imagery beforehand and specify the compressed file as the URL. This can help ensure completeness of the operation and should reduce overall time taken to fetch the source imagery.
We support a few various options for file types. For map processing, input type map_source_image, we support jpeg, png, and tiffs for unprocessed and tiffs for preprocessed maps. For walkthroughs, input type"walkthrough_source_video", we support ".insv"and ".mp4"files. We also support zip archives of these files. If a zip archive is supplied, the archive will be opened and the imagery files uploaded for map processing. Input types image, video, and pano refer to unprocessed assets and will not be including in the photogrammetry processing, but instead stored as stored_assets on the associated plan.
We support zip files larger than 2 GB. We recommend using the basic zip archiver built into computers such as Windows.
/v2/image_transfer
curl -H "Content-Type: application/json" -X POST -d '{"plan_id":"58b0490c95b03d000114a881", "transport": {"type": "https"}, "inputs": [{"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1", "type": "map_source_image"}]}' "https://public-api.dronedeploy.com/v2/image_transfer?api_key={api_key}"
{
"status": "New",
"transport": {"type": "https"},
"inputs": [
{"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1", "type": "map_source_image"}
],
"plan_id": "58b0490c95b03d000114a881",
"failure_info": {},
"id": "58b056b795b03d000114a882",
"run_info": {},
"date_complete": null,
"date_started": null,
"type": "unprocessed",
"date_creation": 1487951543526
}
Including GCPs
If your plan includes GCPs, you can include the CSV in the request by adding it using the `gcp_csv` type. The CSV should not be in a .zip and should be linked directly. You should also include the `epsg` code for the project.
{
"location": "https://www.dropbox.com/s/nc2okgk83k439pj/gcp_northing_easting_ft.csv",
"type": "gcp_csv",
"epsg": 6420
}
Full cURL request:
```
curl -H "Content-Type: application/json" -X POST -d '{"plan_id":"{plan_id}", "transport": {"type": "https"}, "inputs": [{"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1", "type": "map_source_image"}, {"location": "https://www.dropbox.com/s/nc2okgk83k439pj/gcp_northing_easting_ft.csv?dl=1", "type": "gcp_csv", "epsg": 6420}]}' "https://public-api.dronedeploy.com/v2/image_transfer?api_key={api_key}"
```
JSON response when GCP is included:
```
{
"id": "{image_transfer_id}",
"plan_id": "{plan_id}",
"type": "unprocessed",
"status": "new",
"inputs": [
{
"location": "https://www.dropbox.com/s/nc2okgk83k439pj/dropbox_example.zip?dl=1",
"type": "map_source_image"
},
{
"location": "https://www.dropbox.com/s/nc2okgk83k439pj/gcp_northing_easting_ft.csv?dl=1",
"type": "gcp_csv"
}
],
"transport": {
"type": "https"
},
"date_creation": 1701794844591,
"date_started": null,
"date_complete": null
}
Monitor progress
Once the Image Transfer object is received, the DroneDeploy Map Engine will fetch the indicated files based on the account type priority settings. Once the files have been fetched, decompressed (if necessary) and validated, map processing will begin.
You can monitor this process by observing the response from the Image_Transfer, then the Plan object. The status will show "Complete" when the download and photogrammetry processes have concluded respectively.
/v2/image_transfer/{id}
To check the status of your image transfer, request the image_transfer API with the ID you were returned when you posted to the endpoint.
curl "https://public-api.dronedeploy.com/v2/image_transfer/58be0da47915d90001962385?api_key={api_key}"
{"status": "new", "transport": {"type": "https"}, "inputs": [{"location": "https://dl.dropboxusercontent.com/1/view/asdaafasdasd/ImageTransfer/roofofDD23.zip", "type": "map_source_image"}], "plan_id": "58be0d647915d9000196237b", "date_creation": 1488850340459, "date_complete": null, "date_started": null, "type": "unprocessed", "id": "58be0da47915d90001962385"}
/v2/plans/{id}?embed=stored_asset.[download_path,asset_type]
To check the status of your map processing, request the Plan API with the PlanID. The ?embed=stored_asset.[download_path,asset_type] ensures that any stored, unprocessed, assets associated with the plan will be returned in the response body.
curl "https://public-api.dronedeploy.com/v2/plans/58b0490c95b03d000114a881?api_key={api_key}&embed=stored_asset.[download_path,asset_type]"
{
"date_creation": 1487948044752,
"geometry": [],
"id": "58b0490c95b03d000114a881",
"image_count": 1,
"latest_image_transfer_id": "58b056b795b03d000114a882",
"latest_started_map": {
"user_status": "Processing"
},
"location": {},
"log": "1487948044_APIGENERATED",
"name": "My Plan",
"stored_assets": []
}