Mapflow Processing API

Attention

The projects and processings that you create in Mapflow.ai will be available via the API and vice versa. Also, your Mapflow credits are used to run processings via the API. Use the API token to start using the API, which you need to generate in the profile settings (see authorization to work with the Mapflow API).

Important

You should follow the requirements specified on the page with the description of models when uploading your own images for processing through the API of the Mapflow platform. Send a request using data preprocessing to help@geoalert.io.

User

Get user status

GET https://api.mapflow.ai/rest/user/status

Returns user status for the given user account, including:

User limits and billing info (credits, area limits, storage limits)
Default and custom AI-Mapping Models (every User account is connected to the default models, yet specific models have to be linked to the User account by request)
Linked data providers (imagery sources available for processing)
Team memberships (if the user belongs to any team)

If user account is added to the Team accounts - it returns Team’s description as well

Response example:

  {
    "email": "admin@geoalert.io",
    "processedArea": 45221388394,
    "remainingArea": 54778611606,
    "remainingCredits": 2450,
    "areaLimit": 100000000000,
    "maxAoisPerProcessing": 100,
    "memoryLimit": 1000000000,
    "billingType": 0,
    "models": [
        {
            "id": "30ddfd15-04aa-47f6-9ceb-68ce709fd710",
            "name": "🏠 Buildings",
            "description": "Buildings detection and mapping",
            "created": "2023-02-01T08:17:03.871690Z",
            "updated": "2023-05-11T14:24:31.456180Z",
            "blocks": [
              {
                  "name": "Classification",
                  "description": "Classification",
                  "optional": true,
                  "price": 0.0
              },
              {
                  "name": "Polygonization",
                  "description": "Polygonization",
                  "optional": true,
                  "price": 2.0
              },
              {
                  "name": "OSM",
                  "description": "Merge with OSM",
                  "optional": true,
                  "price": 0.0
              }
          ]
        },
        {
            "id": "5d47a57c-3274-4014-aa04-daac416782f7",
            "name": "🚗 Roads",
            "description": "",
            "created": "2023-02-01T08:17:03.371720Z",
            "updated": "2023-05-11T14:24:31.605710Z",
            "pricePerSqKm": 5.0
        }
    ],
    "teams": [
        {
            "teamId": "a6c5a4cf-c693-4441-8bef-028ac0f2d5d9",
            "name": "My New Team",
            "role": "OWNER",
            "activeUntil": null,
            "creditsLimit": null
        }
    ],
    "dataProviders": [
        {
            "id": "5dce9b5a-9f23-4bc6-9b5e-0c7fcb7d8b78",
            "name": "mapbox",
            "displayName": "Mapbox",
            "previewUrl": "https://example.com/tiles/{z}/{x}/{y}.png",
            "previewUrlMaxZoom": 19,
            "price": [
                {
                    "zoom": 18,
                    "priceSqKm": 1.2
                }
            ]
        }
    ],
    "reviewWorkflowEnabled": false
}

Obtain processing statistics

POST https://api.mapflow.ai/rest/processings/stats

Returns user’s processing history with details. This method supports pagination and generic filter/sort expressions. If the user is a Team’s owner, this returns the statistics by all team members.

Params for processing stats:

Optional query parameter type controls the response format (for example, CSV or JSON).

Request body filters:

Filter	Type	Description
page	INTEGER	Page number
perPage	INTEGER	Items per page
sort	STRING	Sort expression
filter	STRING	Filter expression

Sample request:

curl --location 'https://api.mapflow.ai/rest/processings/stats?type=json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--data '{"page":1,"perPage":50,"sort":"created,desc"}'

Sample response:

  {
    "results": [
        {
            "projectName": "Test",
            "name": "test_proc",
            "email": "user1@geoalert.io",
            "area": 536680,
            "cost": 0,
            "created": "2025-02-24T13:34:34.640553Z",
            "completionDate": "2025-02-24T13:35:31.327948Z",
            "status": "OK",
            "percentCompleted": 100,
            "archived": false,
            "dataProvider": null,
            "linkToMap": "https://app.mapflow.ai/projects/c77bad4b-6a2b-49ed-8af4-4d1841aec771/processings/893bcc22-8a3b-47d5-8e56-0d0a83fab25d",
            "scenario": "🏠 Buildings"
        },
        {
            "projectName": "Test new model",
            "name": "test_proc2",
            "email": "user2@geoalert.io",
            "area": 450102,
            "cost": 0,
            "created": "2025-02-24T13:37:55.581373Z",
            "completionDate": "2025-02-24T13:38:22.078667Z",
            "status": "OK",
            "percentCompleted": 100,
            "archived": false,
            "dataProvider": null,
            "linkToMap": "https://app.mapflow.ai/projects/c77bad4b-6a2b-49ed-8af4-4d1841aec771/processings/6ecbd6ae-32cd-499a-aa42-fd0e67d6f9b6",
            "scenario": "🏠 Buildings"
        }
    ],
    "total": 2,
    "count": 2,
    "totalCost": 0,
    "totalArea": 986782
}

Projects

Get project

GET https://api.mapflow.ai/rest/projects/{projectId}

Returns the project with the specified ID.

Response example:

{
    "id": "546d148f-19a1-40d8-8f16-d1e6dabfd204",
    "name": "test",
    "description": "test",
    "progress": {
        "status": "UNPROCESSED",
        "percentCompleted": 0,
        "details": []
    },
    "aoiCount": 0,
    "aoiArea": 0,
    "area": 0,
    "user": {
        "id": "61cd6899-19e8-44a0-97db-b86f1a9b7af4",
        "login": "user@user.com",
        "email": "user@user.com",
        "role": "USER",
        "created": "2019-12-16T16:10:29.492358Z"
    },
    "isDefault": false,
    "created": "2020-05-13T13:00:31.978Z",
    "updated": "2020-05-13T13:00:31.978Z",
    "workflowDefs": [
        {
            "id": "084474b5-e001-456f-a486-f62f5ee1ffe1",
            "name": "🏠 Buildings",
            "created": "2020-08-11T19:57:40.974170Z",
            "updated": "2020-08-11T19:57:40.974172Z"
        }
    ]
}

Get default project

Important

Default project is created for each user upon registration.

GET https://api.mapflow.ai/rest/projects/default

Returns the name and ID of the user’s default project and the user’s account settings.

{
    "id": "ea2281ab-53f0-4839-9d38-8e3648ee377f",
    "name": "Default",
    "description": null,
    "progress": {
        "status": "OK",
        "percentCompleted": 100,
        "details": [
            {
                "status": "OK",
                "count": 1,
                "area": 836643,
                "statusUpdateDate": "2022-12-20T08:14:38.882673Z"
            }
        ],
        "completionDate": "2022-12-20T08:14:38.882673Z"
    },
    "aoiCount": 23,
    "aoiArea": 20885015,
    "area": 20885015,
    "user": {
        "id": "25b12411-bd16-4a31-9842-728264a3aefd",
        "login": "test_user@test.com",
        "email": "test_user@test.com",
        "role": "USER",
        "areaLimit": 25000000,
        "aoiAreaLimit": 25000000,
        "processedArea": 21863903,
        "created": "2022-10-20T14:54:59.630308Z",
        "updated": "2022-12-06T14:00:53.051512Z",
        "isPremium": false
    },
    "isDefault": true,
    "created": "2022-10-20T14:54:59.636598Z",
    "updated": "2022-10-20T14:54:59.636599Z",
    "workflowDefs": [
        {
            "id": "ad7a5460-c903-402b-9c21-b12aa2fc9f69",
            "name": "🏗️ Construction sites",
            "description": null,
            "created": "2022-10-20T14:54:59.690562Z",
            "updated": "2022-10-20T14:54:59.690562Z"
        },
        {
            "id": "decc5854-3a92-4b25-8e5b-895de9fa4ef3",
            "name": "🌲↕️ Forest with heights",
            "description": null,
            "created": "2022-10-20T14:54:59.787793Z",
            "updated": "2022-11-25T13:08:41.124862Z"
        }
    ]
}

Get all projects

GET https://api.mapflow.ai/rest/projects

Returns the list of all user’s projects.

Create project

POST https://api.mapflow.ai/rest/projects

Creates a new project, and returns its immediate state.

Request body example:

{
    "name": "test",
    "description": "test"
}

Name of the project
Arbitrary description of this project

Response: the newly created project contains the project ID and the description of the default AI-models as they are linked to every new project.

Warning

The custom AI-models won’t be linked to the new project automatically.

Rename project

PUT https://api.mapflow.ai/rest/projects/{projectId}

Request body example:

{
  "name": "new name (optional)",
  "description": "new description (optional)"
}

Share project

POST https://api.mapflow.ai/rest/projects/share

Share project with another user by email or user ID.

Share project with the external user:

{
    "projectId": "70f65cfd-285b-4f25-a058-1fd9103a78f9",
    "email": "some-external-user@email.com",
    "role": "MEMBER"
}

Share project with the team user

{
    "projectId": "70f65cfd-285b-4f25-a058-1fd9103a78f9",
    "email": "team-user@myteam.com",
    "role": "OWNER"
}

Note

Provide either email or userId together with projectId and role.

User role parameter:

KEY	VALUE	DESCRIPTION
role	MEMBER	Standard member access to the shared project.
role	OWNER	Project owner access.

Archive project

DELETE https://api.mapflow.ai/rest/projects/{projectId}

Archives the project.

Processing API v2

Warning

Processing API v1 will become DEPRECATED soon. Migrate to API v2 for continued support and improved functionality.

Get all processings

GET https://api.mapflow.ai/rest/processings/v2

Returns the list of the user’s processings (v2 format)

Get all processings by Project Id

GET https://api.mapflow.ai/rest/projects/{projectId}/processings/v2

Returns the list of the user’s processings by user’s project

Get processing by Id

GET https://api.mapflow.ai/rest/processings/{processingId}/v2

Returns the processing with the specified id.

Response Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "description": "string",
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vectorLayer": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "tileJsonUrl": "string",
    "tileUrl": "string"
  },
  "rasterLayer": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tileJsonUrl": "string",
    "tileUrl": "string"
  },
  "workflowDef": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "created": "2025-10-01T20:05:21.819Z",
    "updated": "2025-10-01T20:05:21.819Z",
    "pricePerSqKm": 0,
    "blocks": [
      {
        "name": "string",
        "description": "string",
        "optional": 0,
        "price": 0
      }
    ]
  },
  "aoiCount": 0,
  "aoiArea": 0,
  "area": 0,
  "cost": 0,
  "status": "UNPROCESSED",
  "reviewStatus": {
    "reviewStatus": "ACCEPTED",
    "feedback": "2025-10-01T20:05:21.819Z"
  },
  "rating": {
    "rating": 5,
    "feedback": "Good results"
  },
  "percentCompleted": 0,
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": [
          "string"
        ],
        "mosaicId": "string"
      },
      "imagerySearch": {
        "dataProvider": "orbview",
        "imageIds": [
          "string"
        ],
        "zoom": 0
      },
      "dataProvider": {
        "providerName": "string",
        "zoom": 0
      },
      "userDefined": {
        "sourceType": "XYZ",
        "url": "string",
        "zoom": 0,
        "crs": "string",
        "rasterLogin": "string",
        "rasterPassword": "string"
      }
    },
    "inferenceParams": {
      "key1": "value1",
      "key2": "value2",
      "keyN": "valueN"
    }
  },
  "blocks": [
    {
      "name": "string",
      "enabled": true
    }
  ],
  "meta": {
    "key1": "value1",
    "key2": "value2",
    "keyN": "valueN"
  },
  "messages": [
    {
      "code": "string",
      "parameters": {
        "key": "string",
        "value": "string"
      }
    }
  ],
  "created": "2025-10-01T20:05:21.819Z",
  "updated": "2025-10-01T20:05:21.819Z"
}

Create and run processing v2

POST https://api.mapflow.ai/rest/processings/v2

Creates and runs a new processing with enhanced v2 parameters and configuration options.

Request Body:

{
  "name": "string",
  "description": "string",
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "wdName": "string",
  "wdId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [0, 0],
        [0, 1],
        [1, 1],
        [1, 0],
        [0, 0]
      ]
    ]
  },
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": [
          "string"
        ],
        "mosaicId": "string"
      },
      "imagerySearch": {
        "dataProvider": "orbview",
        "imageIds": [
          "string"
        ],
        "zoom": 0
      },
      "dataProvider": {
        "providerName": "string",
        "zoom": 0
      },
      "userDefined": {
        "sourceType": "XYZ",
        "url": "string",
        "zoom": 0,
        "crs": "string",
        "rasterLogin": "string",
        "rasterPassword": "string"
      }
    },
    "inferenceParams": {
      "key1": "value1",
      "key2": "value2",
      "keyN": "valueN"
    }
  },
  "meta": {
    "key1": "value1",
    "key2": "value2",
    "keyN": "valueN"
  },
  "blocks": [
    {
      "name": "string",
      "enabled": true
    }
  ]
}

Note

Provide either wdId or wdName to select the workflow definition.

Response Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "description": "string",
  "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vectorLayer": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "tileJsonUrl": "string",
    "tileUrl": "string"
  },
  "rasterLayer": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "tileJsonUrl": "string",
    "tileUrl": "string"
  },
  "workflowDef": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "created": "2025-10-01T20:05:56.690Z",
    "updated": "2025-10-01T20:05:56.690Z",
    "pricePerSqKm": 0,
    "blocks": [
      {
        "name": "string",
        "description": "string",
        "optional": 0,
        "price": 0
      }
    ]
  },
  "aoiCount": 0,
  "aoiArea": 0,
  "area": 0,
  "cost": 0,
  "status": "UNPROCESSED",
  "reviewStatus": {
    "reviewStatus": "ACCEPTED",
    "feedback": "2025-10-01T20:05:56.690Z"
  },
  "rating": {
    "rating": 5,
    "feedback": "Good results"
  },
  "percentCompleted": 0,
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": [
          "string"
        ],
        "mosaicId": "string"
      },
      "imagerySearch": {
        "dataProvider": "orbview",
        "imageIds": [
          "string"
        ],
        "zoom": 0
      },
      "dataProvider": {
        "providerName": "string",
        "zoom": 0
      },
      "userDefined": {
        "sourceType": "XYZ",
        "url": "string",
        "zoom": 0,
        "crs": "string",
        "rasterLogin": "string",
        "rasterPassword": "string"
      }
    },
    "inferenceParams": {
      "key1": "value1",
      "key2": "value2",
      "keyN": "valueN"
    }
  },
  "blocks": [
    {
      "name": "string",
      "enabled": true
    }
  ],
  "meta": {
    "key1": "value1",
    "key2": "value2",
    "keyN": "valueN"
  },
  "messages": [
    {
      "code": "string",
      "parameters": {
        "key": "string",
        "value": "string"
      }
    }
  ],
  "created": "2025-10-01T20:05:56.690Z",
  "updated": "2025-10-01T20:05:56.690Z"
}

Calculate processing cost v2

POST https://api.mapflow.ai/rest/processing/cost/v2

Calculate processing cost v2 with enhanced parameters and configuration options.

Request Body:

{
  "wdId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [0, 0],
        [0, 1],
        [1, 1],
        [1, 0],
        [0, 0]
      ]
    ]
  },
  "areaSqKm": 0,
  "params": {
    "sourceParams": {
      "myImagery": {
        "imageIds": [
          "string"
        ],
        "mosaicId": "string"
      },
      "imagerySearch": {
        "dataProvider": "orbview",
        "imageIds": [
          "string"
        ],
        "zoom": 0
      },
      "dataProvider": {
        "providerName": "string",
        "zoom": 0
      },
      "userDefined": {
        "sourceType": "XYZ",
        "url": "string",
        "zoom": 0,
        "crs": "string",
        "rasterLogin": "string",
        "rasterPassword": "string"
      }
    },
    "inferenceParams": {
      "key1": "value1",
      "key2": "value2",
      "keyN": "valueN"
    }
  },
  "blocks": [
    {
      "name": "string",
      "enabled": true
    }
  ],
  "meta": {
    "key1": "value1",
    "key2": "value2",
    "keyN": "valueN"
  }
}

Note

Provide either geometry or areaSqKm (or both) to estimate cost.

Response Example:

Processing API v1

Note

v1 uses a flat params map (string values). For nested sourceParams and inferenceParams use the v2 endpoints.

Get all processings

GET https://api.mapflow.ai/rest/processings

Returns the list of the user’s processings (v1 format)

Get all processings by Project Id

GET https://api.mapflow.ai/rest/projects/{projectId}/processings

Returns the list of the user’s processings by user’s project

Get processing by Id

GET https://api.mapflow.ai/rest/processings/{processingId}

Returns the processing with the specified id.

Response example:

{
  "id": "65285409-ac88-4fc0-a937-193cf42c2343",
  "name": "Test processing",
  "description": null,
  "projectId": "a45aa059-fc95-4da0-80e9-2f258fa42c3f",
  "vectorLayer": {
      "id": "726bdc81-4c43-44ba-9d1b-ca5ed53f23fe",
      "name": "Test processing",
      "tileJsonUrl": "https://app.mapflow.ai/api/layers/4f84c84a-3678-4a11-bd20-dac6f230b08f.json",
      "tileUrl": "https://app.mapflow.ai/api/layers/4f84c84a-3678-4a11-bd20-dac6f230b08f/tiles/{z}/{x}/{y}.vector.pbf"
  },
  "rasterLayer": {
      "id": "9cb1df8d-d26c-4458-8e4b-ffd03871edbf",
      "tileJsonUrl": "https://app.mapflow.ai/api/v0/cogs/tiles.json?uri=s3://mapflow-rasters/db3f192f-010d-4fc5-9cbe-f44bc569ba59",
      "tileUrl": "https://app.mapflow.ai/api/v0/cogs/tiles/{z}/{x}/{y}.png?uri=s3://mapflow-rasters/db3f192f-010d-4fc5-9cbe-f44bc569ba59"
  },
  "workflowDef": {
      "id": "c6a71c32-972c-4d67-95a1-e9f3dfc033c9",
      "name": "Buildings (⭐️ Aerial imagery)",
      "description": "Custom model: segmentation of buildings in aerial imagery at resolution 10 cm/pixel",
      "created": "2023-02-07T12:07:35.259144Z",
      "updated": "2023-09-01T13:03:20.905987Z",
      "pricePerSqKm": 33.0,
      "blocks": []
  },
  "aoiCount": 1,
  "aoiArea": 12010038,
  "area": 12010038,
  "cost": 1638,
  "status": "OK",
  "reviewStatus": null,
  "rating": null,
  "percentCompleted": 100,
  "params": {
      "url": "https://app.mapflow.ai/api/v0/cogs/tiles/{z}/{x}/{y}.png?uri=s3://white-maps-rasters/0617c425-9bfa-45a3-b2ea-46020e48d775",
      "source_type": "xyz",
      "crs": "EPSG:3857"
  },
  "blocks": [],
  "meta": {
      "source": "tif",
      "source-app": "qgis",
      "version": "1.7.0"
  },
  "messages": [],
  "created": "2023-03-29T06:48:35.103854Z",
  "updated": "2023-07-09T13:32:25.540726Z"
}

If the processing failed, the response also contains the code and parameters of the error in the messages section. If different AOIs failed with the same error, only one of the repeated errors is returned. Example of the failed processing response:

{
  "id": "6ad89b64-38fd-408f-acbb-75035ec52787",
  "status": "FAILED",
  "percentCompleted": 0,
  "messages": [
    {
      "code": "source-validator.PixelSizeTooHigh",
      "parameters": {
        "max_res": "1.2",
        "level": "error",
        "actual_res": "5.620983603290215"
      }
    }
  ]
}

Possible error codes, parameters and desctiptions see in Error Messages

▶️ Run the processing

POST https://api.mapflow.ai/rest/processings

Runs an imagery analysis processing, and returns its immediate state. Request body sample:

{
    "name": "Test",
    "description": "A simple test",
    "projectId": "20f05e39-ccea-4e26-a7f3-55b620bf4e31",
    "wdName": "🏠 Buildings",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [37.29836940765381, 55.63619642594767],
            [37.307724952697754, 55.63619642594767],
            [37.307724952697754, 55.64024152130109],
            [37.29836940765381, 55.64024152130109],
            [37.29836940765381, 55.63619642594767]
          ]
        ]
    },
    "params": {
        "data_provider": "Mapbox",
        "zoom": "18"
    },
    "meta": {
        "test": "test"
    }
}

Note

To process a user-provided image (see Upload image section), set parameters as follows:

"params": {
    "source_type": "local",
    "url": "s3://users-data/user@email.com_eaf9e720-c6de-4d9b-8aec-52296d43f0c4/1e7fc660-7d0a-4632-9e6c-e95cf20e62b9/b97e9154-a356-450c-990b-fb1692d404ec.tif"
}

Response: the newly created processing.

Customize processing with the options

POST https://api.mapflow.ai/rest/processings

Processing workflow can be customized with enabling or disabling some model options. The number of options depends on the model and a scenario.

Request body example

{
    "blocks": [
        {
            "name": "Simplification",
            "enabled": false
        },
        {
            "name": "Classification",
            "enabled": true
        }
    ]
}

The “options” can be retrieved for every model in the models linked to the user – through the user/status request.

Processing cost

POST https://api.mapflow.ai/rest/processing/cost

To find out the cost of processing without running it, you can use this method. Returns the cost of the processing in credits given the model, the area and the data source.

Request body example:

{
  "wdId": "8cb13006-a299-4df6-b47d-91bd63de947f",
  "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            37.29836940765381,
            55.63619642594767
          ],
          [
            37.307724952697754,
            55.63619642594767
          ],
          [
            37.307724952697754,
            55.64024152130109
          ],
          [
            37.29836940765381,
            55.64024152130109
          ],
          [
            37.29836940765381,
            55.63619642594767
          ]
        ]
      ]
  },
  "params": {
    "data_provider": "Mapbox"
  }
}

Response example:

30

Note

You can find out the details like workflow definition ID (wdId) using this method:

GET api.mapflow.ai/rest/user/status

Rename processing

PUT https://api.mapflow.ai/rest/processings/{processingId}

Request body example:

{
  "name": "new name (optional)",
  "description": "new description (optional)"
}

Restart processing

POST https://api.mapflow.ai/rest/processings/{processingId}/restart

Restarts failed partitions of this processing. Doesn’t restart non-failed partitions. Each workflow is restarted from the first failed stage. Thus, the least possible amount of work is performed to try and bring the processing into successful state.

Link processing to another project

PUT https://api.mapflow.ai/rest/processings/{processingId}

Links processing to another project by project ID

curl --location --request PUT 'https://api.mapflow.ai/rest/processings/{processingId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--data-raw '{"projectId": "new_project_id"}'

Delete processing

DELETE https://api.mapflow.ai/rest/processings/{processingId}

Deletes this processing. Cascade deletes any child entities.

Get processing AOIs

GET https://api.mapflow.ai/rest/processings/{processingId}/aois

Note

Deprecated endpoint.

Returns a list of the defined geographical areas for processing in GeoJSON.

Response sample:

[
    {
        "id": "b86127bb-38bc-43e7-9fa9-54b37a0e17af",
        "status": "IN_PROGRESS",
        "percentCompleted": 0,
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        37.29836940765381,
                        55.63619642594767
                    ],
                    [
                        37.29836940765381,
                        55.64024152130109
                    ],
                    [
                        37.307724952697754,
                        55.64024152130109
                    ],
                    [
                        37.307724952697754,
                        55.63619642594767
                    ],
                    [
                        37.29836940765381,
                        55.63619642594767
                    ]
                ]
            ]
        },
        "area": 265197,
        "messages": []
    }
]

Download processing results

GET https://api.mapflow.ai/rest/processings/{processingId}/result

Returns Geojson results of this processing as an octet stream. Should only be called on a successfully completed processing. Optional query parameter aoiId filters results to a specific AOI.

Upload images

Note

❗️ Use Mapflow Data API to create a mosaic and upload one or more images
Use s3 link from the "image_url" as an "url" param to Create processing

Reference

Note

The tables below describe v2 request parameters. For v1, params is a flat string map (see the v1 section above).

Params	Type	Description
geometry*	Object	Processing area in GeoJSON format (Polygon or MultiPolygon).
name	String	Processing name (optional).
description	String	Processing description (optional).
projectId	String	Project ID (optional). If omitted, default project is used.
wdId / wdName	String	Workflow definition ID or name (provide one).
params	Object	Processing parameters.
params.sourceParams	Object	Data source parameters (required when params is provided).
params.sourceParams.dataProvider	Object	Use a linked data provider.
params.sourceParams.imagerySearch	Object	Use imagery search results.
params.sourceParams.myImagery	Object	Use images or mosaic from Mapflow storage.
params.sourceParams.userDefined	Object	Use a custom imagery source.
params.inferenceParams	Object	Model-specific inference parameters.
blocks	Array	Model options to enable/disable.
meta	Object	Optional metadata key-value map.

Create new processing with default Data provider

  "params": {
    "sourceParams": {
        "dataProvider": {
            "providerName": "Mapbox",
            "zoom": 18
        }
    }
}

Create new processing with User custom URl

  "params": {
    "sourceParams": {
        "userDefined": {
            "url": "https://app.mapflow.ai/api/v0/cogs/tiles/{z}/{x}/{y}.png?uri=s3://white-maps-rasters/0617c425-9bfa-45a3-b2ea-46020e48d775",
            "sourceType": "XYZ",
            "zoom": 19,
            "crs": "EPSG:3857",
            "rasterLogin": "qwerty",
            "rasterPassword": "12345678"
        }
    }
}

Create new processing with My Imagery (Image collection)

  "params": {
    "sourceParams": {
        "myImagery": {
            "imageIds": ["0c26a0d3-96d8-4ed5-aa62-3843d1d7905c"],
            "mosaicId": "0617c425-9bfa-45a3-b2ea-46020e48d775"
        }
    }
}

Create new processing with My Imagery (single Image)

  "params": {
    "sourceParams": {
        "myImagery": {
            "imageIds": ["0c26a0d3-96d8-4ed5-aa62-3843d1d7905c"]
        }
    }
}

VALUE	DESCRIPTION
XYZ	The URL to the imagery service in “xyz” format
TMS	The similar to “xyz” with reverse “y” coordinate
QUADKEY	The one-dimensional index key that usually preserves the proximity of tiles in “xy” space (Bing Maps tile format)
SENTINEL_L2A	Sentinel-2 L2A source type
LOCAL	File of image in GeoTIFF format

VALUE	DESCRIPTION	MODEL input (m/px), num of bands	ZOOM LEVEL	OPTIONS
🏠 Buildings	Detects buildings & classifies them	0.5, 1-3 (RGB)	17–18	Simplification, OSM, Classification
🌲 Forest	Detects tree-like vegetation	0.5, 3 (RGB)	17-18	Heights
🚗 Roads	Detects roads and returns them as polygons / linestrings	0.5, 3 (RGB)	17–18
🏗️ Construction	Detects construction sites	0.5, 3 (RGB)	17–18

VALUE	Description
UNPROCESSED	The processing is not started yet
IN_PROGRESS	The processing is going (or is in the queue)
AWAITING	The processing is awaiting data from the imagery supplier
CANCELLED	The processing was stopped and cancelled
REFUNDED	The cost of processing was refunded by the administrator
FAILED	The processing ended unsuccessfully - change wrong params or try to restart
OK	The processing is finished at 100 percent completed
CANCELLED	The processing was cancelled

VALUE	Description
ACCEPTED	Results accepted
NOT_ACCEPTED	Results rejected
REFUNDED	Results refunded
IN_REVIEW	Results are under review

Error messages in API

List of messages and params that can be found in the `messages` section in case of the failed processings
Error code	Parameters	Description
source-validator.UrlMustBeString	url_type	Key ‘url’ in your request must be a string, got {url_type} instead.
source-validator.UrlMustBeLink		Your URL must be a link starting with “http://” or “https://”.
source-validator.UrlFormatInvalid	parse_error_message	Format of ‘url’ is invalid and cannot be parsed. Error: {parse_error_message}
source-validator.ZoomMustBeInteger	actual_zoom	Zoom must be either empty, or integer, got {actual_zoom}
source-validator.InvalidZoomValue	actual_zoom}	Zoom must be between 0 and 22, got {actual_zoom}
source-validator.TooHighZoom	max_zoom, actual_zoom	Zoom must be not higher than {max_zoom}, got {actual_zoom}
source-validator.TooLowZoom	min_zoom, actual_zoom	Zoom must be not lower than {min_zoom}, got {actual_zoom}
source-validator.UrlBlacklisted	url	The specified basemap {url} is forbidden for processing because it contains a map, not satellite image. Our models are suited for satellite imagery.
source-validator.ImageMetadataMustBeDict		Image metadata must be a dict (json)
source-validator.ImageMetadataKeyError		Image metadata must have keys: crs, transform, dtype, count
source-validator.S3URLError	actual_s3_link	URL of the image at s3 storage must be a string starting with s3://, got {actual_s3_link}
source-validator.LocalRequestKeyError		Request must contain either ‘profile’ or ‘url’ keys
source-validator.ReadFromS3Failed	s3_link	Failed to read file from {s3_link}.
source-validator.ImageReadError		We could not open and read the image you have uploaded
source-validator.BadImageProfile	profile, required_keys	Image profile (metadata) must have keys {required_keys}, got profile {profile}
source-validator.DtypeNotAllowed	required_dtypes, request_dtype	Image data type (Dtype) must be one of {required_dtypes}, got {request_dtype}
source-validator.NChannelsNotAllowed	required_nchannels, real_nchannels	Number of channels in image must be one of {required_nchannels}. Got {real_nchannels}
source-validator.PixelSizeTooLow	actual_res, min_res	Spatial resolution of you image is too low: pixel size is {actual_res}, minimum allowed pixel size is {min_res}
source-validator.PixelSizeTooHigh	actual_res, max_res	Spatial resolution of you image is too high: pixel size is {actual_res}, maximum allowed pixel size is {max_res}
source-validator.ImageCheckError	checked_param, message, metadata	Error occurred during image {checked_param} check: {message}. Image metadata = {metadata}.
source-validator.QuadkeyLinkFormatError		Your ‘url’ doesn’t match the format, Quadkey basemap must be a link containing “q” placeholder.
source-validator.SentinelInputStringKeyError		Sentinel_L2A request must contain field named ‘url’ with string value
source-validator.SentinelInputStringFormatError	input_string	Input string {input_string} is of unknown format. It must represent Sentinel-2 granule ID
source-validator.GridCellOutOfBound	actual_cell, allowed_cells	Selected Sentinel-2 image cell is {actual_cell}, this model is for the cells: {allowed_cells}
source-validator.AOINotInCell	actual_cell	AOI does not intersect the selected Sentinel-2 granule {actual_cell}
source-validator.MonthOutOfBounds	actual_month, allowed_months	Selected Sentinel-2 image month is {actual_month}, this model is for: {allowed_months}
source-validator.TMSLinkFormatError		You request TMS basemap link doesn’t match the format, it must be a link containing ‘{x}’, ‘{y}’, ‘{z}’ placeholders, correct it and start processing again.
source-validator.RequirementsMustBeDict	requirements_type	Requirements must be dict, got {requirements_type}.
source-validator.RequestMustBeDict	request_type	Request must be dict, got {request_type}.
source-validator.RequestMustHaveSourceType		Request must contain “source_type” key
source-validator.SourceTypeIsNotAllowed	source_type, allowed_sources	Source type {source_type} is not allowed. Use one of: {allowed_sources}
source-validator.RequiredSectionMustBeDict	required_section_type	“Required” section of the requirements must contain dict, not {required_section_type}
source-validator.RecommendedSectionMustBeDict	recommended_section_type	“Recommended” section of the requirements must contain dict, not {recommended_section_type}
source-validator.XYZLinkFormatError		You XYZ basemap link doesn’t match the format, it must be a link containing ‘{x}’, ‘{y}’, ‘{z}’ placeholders.
source-validator.TaskMustContainAoi		Task for source-validation must contain area of interest (‘geometry’ section)
source-validator.UnhandledException		Internal error in process of data source validation. We are working on the fix, our support will contact you.
source-validator.internalError		Internal error in process of data source validation. We are working on the fix, our support will contact you.
dataloader.internalError		Internal error in process of loading data. We are working on the fix, our support will contact you.
dataloader.InternalError		Internal error in process of loading data. We are working on the fix, our support will contact you.
dataloader.UnknownSourceType	allowed_source_types, real_source_types	Wrong source type {real_source_type}. Specify one of the allowed types {allowed_source_types}.
dataloader.MemoryLimitExceeded	allowed_size, estimated_size	Your data loading task requires {estimated_size} MB of memory, which exceeded allowed memory limit {allowed_size}
dataloader.LoaderArgsError	argument_name, argument_type, expected_type	Dataloader argument {argument_name} has type {argument_type}, excpected to be {expected_type}
dataloader.WrongChannelsNum	expected_nchannels, real_nchannels	Loaded tile has {real_nchannels} channels, required number is {expected_nchannels}
dataloader.WrongTileSize	expected_size, real_size	Loaded tile has size {real_size}, expected tile size is {expected_size}
dataloader.TileNotLoaded	tile_location, status	Tile at location {tile_location} cannot be loaded, server response is {status}
dataloader.CrsIsNotSupported		Internal error in process of loading data. We are working on the fix, our support will contact you.
dataloader.MaploaderInternalError		Internal error in process of loading data. We are working on the fix, our support will contact you.
dataloader.SentinelLoaderInternalError		Internal error in process of loading data. We are working on the fix, our support will contact you.
raster-processor.internalError		Internal error in process of data preparation. We are working on the fix, our support will contact you.
inference.internalError		Internal error in process of data processing. We are working on the fix, our support will contact you
vector-processor.internalError		Internal error in process of data processing. We are working on the fix, our support will contact you