Mapflow processing API

Внимание

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

Примечание

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 the given user account. If user account is linked to the Team - 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
        },
        {
            "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

Важно

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",
    "addDefaultWds": true
}

//Name of the project

//Arbitrary description of this project

//Add default processing pipelines to the project

Response: the newly created project.

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":"err",
    "description":"",
    "projectId":"598ab24e-6ea1-42ad-a67d-eefb4cf10d84",
    "vectorLayer": {
        "id": "544a7a6b-bc7f-4fbe-9caf-b2990e8616f9",
        "name": "err",
        "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.

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.

Link processing to another project

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

Links processing to another project by project ID

curl --location --request PUT 'https://api.mapflow.ai/rest/processings/{processing_id}' \
--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

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

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

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