Map Processing API

Have more questions? Submit a request
This page describe how to use the DroneDeploy map processing engine as a service
Generate maps from photos via our API
You can produce high quality 3D maps from your source image sets without building your own photogrammetry pipeline. We'll take you through setting up a plan and image transfer object, adding images, running exports, and accessing the generated tiles.

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 '{"name":"My Plan", "workflow": {"job_type": "2d", "quality": 9}}' "https://public-api.dronedeploy.com/v2/plans?api_key=f78b0a0d66274fd5a8684c49deb9d83d"
{
  "id": "58b0490c95b03d000114a881"
}
  • 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 to API 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"). Defaults to "2d".
  • quality: The processing quality of the map. Available values are 3, 6 and 9. A lower value means poorer quality, but much better processing speed. Defaults to 9.
  • record_type: The type of the plan being created (map, pano, video, etc.). Available values are "map_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 to null. To create a valid geometry, here are some tips:
    1. 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.
    2. 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.
    3. Do not repeat coordinates.
A Note About Processing Area
It is wise to double-check the geometry specified for your map plan. Ensure the geometry includes all images in the image set, otherwise, map failures may occur.

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. 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
}

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": []
}
REST API Announcement
The REST APIs in this documentation are our legacy APIs and no longer under active development. Please go to our API explorer page and our developer page for our new more capable GraphQL based APIs.

Articles in this section

Was this article helpful?
0 out of 0 found this helpful