Mapflow processing API

Attention

The projects and processings that you create in Mapflow.ai won’t be available via the API and vice versa. Neither can your Mapflow credits be 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).

Note

Preview results

Check and run this Postman collection for 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 status

Returns user status for the the given user account, including: * User 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 Administrator) * Default and custom Satellite imagery (every User account is connected to the default data providers, yet specific models have to be linked to the User account by Administrator))

Note

If user account is linked to the Team accounts - 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,
    "aoiArea": 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,
    "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.

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)"
}

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":"998194d7-dbe1-464d-acb2-4298e55e1996",
    "name":"test",
    "description":"",
    "projectId":"598ab24e-6ea1-42ad-a67d-eefb4cf10d84",
    "vectorLayer": {
        "id": "544a7a6b-bc7f-4fbe-9caf-b2990e8616f9",
        "name": "test",
        "tileJsonUrl": "https://vector-production.mapflow.ai/api/layers/293k63cc-cde6-4f6a-80d7-b5af6b6ba2ad.json",
        "tileUrl": "https://vector-production.mapflow.ai/api/layers/293k63cc-cde6-4f6a-80d7-b5af6b6ba2ad/tiles/{z}/{x}/{y}.vector.pbf"
    },
    "rasterLayer": {
        "id": "0ffc6ri8-b080-41e8-957c-3dd07f933f0a",
        "tileJsonUrl": "https://rasters-production.mapflow.ai/api/v0/cogs/tiles.json?uri=s3://white-maps-rasters/b1089927-cb61-473e-b9d5-caa7cbe8062c",
        "tileUrl": "https://rasters-production.mapflow.ai/api/v0/cogs/tiles/{z}/{x}/{y}.png?uri=s3://white-maps-rasters/b1089927-cb61-473e-b9d5-caa7cbe8062c"
    },
    "workflowDef": {
        "id": "e973aa99-3422-46b3-a968-d8a252b64345",
        "name": "Buildings Detection",
        "description": "",
        "created": "2022-07-06T14:15:11.187892Z",
        "updated":"2022-07-06T14:15:11.187894Z"
    },
    "aoiCount":1,
    "aoiArea":798784,
    "status":"OK",
    "percentCompleted":100,
    "meta":{},
    "messages":[],
    "created":"2022-08-11T13:49:17.386035Z",
    "updated":"2022-08-11T13:49:17.386035Z"
}

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

Create 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.
        "source_type": "xyz",
        "url": "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
    },
    "meta": {                             #Arbitrary string key-value for this processing (metadata). Optional.
        "test": "test"
    }
}

To process a user-provided raster (see Upload GeoTIFF for processing section), set parameters as follows:

"params": {
    "source_type": "tif",
    "url": "s3://mapflow-rasters/9764750d-6047-407e-a972-5ebd6844be8a/raster.tif"
}

Response: the newly created processing.

Customize processing with the workflow options

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

Processing workflow can be custoized with enabling some model options. The “options” can be retrieved through the user/status request as {"blocks": [{"name":<>, "displayName": <>, "optional":true, "price": <>}] in the models list.

Request body example

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

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

Warning

This is the legacy method and is going to be deprecated. Use the new Mapflow Data API instead.

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

Can be used to upload a raster for further processing. Returns url to the uploaded raster. This url can be referenced when starting a processing. The request is a multipart request whith the only part “file” - which contains the raster. Request example with cURL:

curl -X POST \
https://api.mapflow.ai/rest/rasters \
-H 'authorization: <Insert auth header value>' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file=@custom_raster.tif

Response example:

{"url": "s3://mapflow-rasters/9764750d-6047-407e-a972-5ebd6844be8a/raster.tif"}

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}, maximum allowed pixel size is {max_res}

source-validator.PixelSizeTooHigh

actual_res, max_res

Spatial resolution of you image is too low: 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