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: - User limits - Default and custom Модели ИИ-Картографирования (every User account is connected to the default models, yet specific models have to be linked to the User account by Administrator) - Default and custom Спутниковые снимки (every User account is linked to the default data providers, yet specific commercial providers have to be linked to the User account by Administrator)

Примечание

If user account is linked 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 Geoalert 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": "495192d6-5dfc-4167-842e-3d76d8abe244",
            "name": "🚜 Fields (Sentinel-2)",
            "description": null,
            "created": "2022-10-20T14:54:59.748459Z",
            "updated": "2022-10-20T14:54:59.748459Z"
        },
        {
            "id": "9c2ceb15-2063-49b2-afec-d1752cbab2e1",
            "name": "🚗 Roads",
            "description": null,
            "created": "2022-10-20T14:54:59.865654Z",
            "updated": "2022-10-20T14:54:59.865654Z"
        },
        {
            "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 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": "tif",
    "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.

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 processing

Parameter values

Default AI models

VALUE

DESCRIPTION

MODEL resolution (m/px), num of input bands

🏠 Buildings

Detects buildings & classifies them

0.5, 3 (RGB)

🌲 Forest

Detects tree-like vegetation

2, 3 (RGB)

🚗 Roads

Detects roads and returns them as polygons / linestrings

1, 3 (RGB)

🚜 Fields (hi-res)

Detects cropland fields

0.5, 3 (RGB)

🚜 Fields (Sentinel-2)

Detects cropland fields using free Sentinel-2 imagery

10 m/px, 10 (multispectral)

🏗️ Construction

Detects cropland fields

0.5, 3 (RGB)

source_type

VALUE

DESCRIPTION

XYZ

The URL to the imagery service in “xyz” format, e.g. https://tile.openstreetmap.org/{z}/{x}/{y}.png

TMS

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

WMS

(❗️❗️Deprecated) The URL to the imagery service in “wms” format, e.g. https://services.nationalmap.gov/arcgis/services/ USGSNAIPImagery/ImageServer/WMSServer

Quadkey

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

tif/tiff

File of image in georeferenced tiff (GeoTIFF) format

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

Error messages in API

List of messages and parameters 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