Mapflow processing API

Внимание

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

Примечание

Preview results

Check and run this Postman collection for API.

Важно

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 status

Returns user status for the given user account, including:

If user account is added to the Командные аккаунты - it returns Team’s description as well

Response example:

  {
    "email": "admin@geoalert.io",
    "processedArea": 45221388394,
    "remainingArea": 54778611606,
    "areaLimit": 100000000000,
    "memoryLimit": 1000000000,
    "models": [
        {
            "id": "30ddfd15-04aa-47f6-9ceb-68ce709fd710",
            "name": "🏠 Buildings",
            "description": "",
            "created": "2023-02-01T08:17:03.871690Z",
            "updated": "2023-05-11T14:24:31.456180Z",
            "pricePerSqKm": 13.0,
            "blocks": [
              {
                  "name": "Classification",
                  "displayName": "Classification",
                  "optional": true,
                  "price": 3.0
              },
              {
                  "name": "Simplification",
                  "displayName": "Polygonization",
                  "optional": true,
                  "price": 5.0
              },
              {
                  "name": "OSM",
                  "displayName": "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
        }
    ]
}

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,
    "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

Важно

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,
    "area": 20885015,
    "user": {
        "id": "25b12411-bd16-4a31-9842-728264a3aefd",
        "login": "test_user@test.com",
        "email": "test_user@test.com",
        "role": "USER",
        "areaLimit": 50000000,
        "aoiAreaLimit": 50000000,
        "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.

Предупреждение

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 the external or a team user depending on the contribution rights.

  1. Share project with the external user:

{
    "projectId": "70f65cfd-285b-4f25-a058-1fd9103a78f9",
    "email": "some-external-user@email.com",
    "role": "readonly"
}
  1. Share project with the team user

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

User role parameter:

Примечание

The «readonly» role is applicable for any user. The «contributor+» role is applicable for sharing projects inside the team.

KEY

VALUE

DESCRIPTION

role

readonly

User can view project, download results but can’t create and run processing.

role

contributor

User can view project, download results and create and run processing.

role

maintainer

User can view project, download results, create, run and delete processing + share project.

role

owner

User can do everything above + assign and remove the project owner.

Delete project

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

Deletes the project. Cascade deletes any child entities.

Processings

Get all processings

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

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

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,
  "area": 12010038,
  "cost": 1638,
  "status": "OK",
  "reviewStatus": null,
  "rating": null,
  "percentCompleted": 100,
  "params": {
      "url": "https://rasters-production.mapflow.ai/api/v0/cogs/tiles/{z}/{x}/{y}.png?uri=s3://mapflow-rasters/4738260d-0fab-479f-beff-633d50a388f0",
      "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

Processing cost

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

If you want 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

Примечание

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

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

Run the processing

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

Runs a processing, and returns its immediate state. Request body sample:

{
    "name": "Test",                                      //Name of this processing. Optional.
    "description": "A simple test",                      //Arbitrary description of this processing. Optional.
    "projectId": "20f05e39-ccea-4e26-a7f3-55b620bf4e31", //Project id. Optional. If not set, the user's default project will be applied.
    "wdName": "🏠 Buildings",                            //The name of a workflow (AI model). Could be "🏠 Buildings", or "🌲 Forest", etc. See ref. below
    "geometry": {                                        //A geojson geometry of the area of processing.
        "type": "Polygon",
        "coordinates": [
          [
            [
              37.29836940765381,
              55.63619642594767
            ],
            [
              37.307724952697754,
              55.63619642594767
            ],
            [
              37.307724952697754,
              55.64024152130109
            ],
            [
              37.29836940765381,
              55.64024152130109
            ],
            [
              37.29836940765381,
              55.63619642594767
            ]
          ]
        ]
    },
    "params": {                           //Arbitrary string parameters of this processing. Optional.
        "data_provider": "Mapbox",
    },
    "meta": {                             //Arbitrary string key-value for this processing (metadata). Optional.
        "test": "test"
    }
}

Примечание

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.

✍️ Params to run the processing

Params

Type

Description

geometry*

Array

Processing area in GeoJSON format, type – Polygon or Multipolygon.

name

String

Processing name. If not specified, an automatically generated ID will be assigned

projectId

String

ID of the project in which the processing is created (if not specified, it is created in the user’s default project)

wdId* /

String

Processing scenario (AI Model) ID. wdName can be specified instead

wdName*

String

Processing scenario (AI Model) name. wdId can be specified instead

params

Array

Data source parameters. If not specified, the first default data source will be used.

blocks

Array

Processing options that are specified for the Model.

meta

Array

Optional metadat as a key:value array

✍️ Default AI models

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

✍️ Params to specify the data source

Params

Type

Description

Sample values

name

String

Name of the featured data provider if its available for the current account.

  1. «Mapbox»

  2. «arcgis_world_imagery»

  3. «Global mosaic 2022»

url

String

Custom data provider url

«my-tile-server.com/{z}/{x}/{y}»

source_type

String

Source type of the custom data provider. Type «local» can be specified to use a user’s file from the Mapflow storage

  1. «XYZ»

  2. «TMS»

  3. «local»

zoom

String

Zoom level

«18»

✍️ Params to specify the «source_type»

VALUE

DESCRIPTION

XYZ

The URL to the imagery service in “xyz” format

TMS

The similar to «xyz» with reverse «y» coordinate

WMS

(❗️❗️Deprecated) The URL to the imagery service in “wms” format

Quadkey

The one-dimensional index key that usually preserves the proximity of tiles in «xy» space (Bing Maps tile format)

local

File of image in GeoTIFF format

Processing status

VALUE

Description

UNPROCESSED

The processing is not started yet

IN_PROGRESS

The processing is going (or is in the queue)

FAILED

The processing ended unsuccessfuly - change wrong params or try to restart

OK

The processing is finished at 100 percent completed

IN_REVIEW

The additional status enabled by request (if the results are under review)

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.

Response example:

"models":
[

    {
        "id": "c2e857fe-1bf6-4e7a-b9f4-d5339c46d357",
        "name": "Forest",
        "description": "Default model: segmentation of forested areas with assinment of height classes; thresholds are 4 and 10 meters",
        "created": "2023-07-26T08:14:18.739968Z",
        "updated": "2023-08-11T04:58:40.907896Z",
        "pricePerSqKm": 0.0,
        "blocks": [
            {
                "name": "Segmentation",
                "displayName": "Segmentation",
                "optional": false,
                "price": 8.0
            },
            {
                "name": "Heights",
                "displayName": "Height estimation",
                "optional": true,
                "price": 20.0
            }
        ]
    }
]

Rename processing

PUT https://api.mapflow.ai/rest/processing/{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.

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

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": []
    }
]

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

Upload images

Примечание

  1. ❗️ Use Mapflow Data API to create a mosaic and upload one or more images

  2. Use s3 link from the "image_url" as an "url" param to Run the processing

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