Mapflow processing API
Attention
The projects and processings that you create in Mapflow.ai will be available via the API and vice versa. Also, your Mapflow credits are used to run processings via the API. Use the API token to start using the API, which you need to generate in the profile settings (see authorization to work with the Mapflow API).
Important
You should follow the requirements specified on the page with the description of models when uploading your own images for processing through the API of the Mapflow platform. Send a request using data preprocessing to help@geoalert.io.
User status
- Returns user status for 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 linked to the default data providers, yet specific commercial providers have to be linked to the User account by Administrator)
If user account is added to the Team accounts - it returns Team’s description as well
Response example:
{
"email": "admin@geoalert.io",
"processedArea": 45221388394,
"remainingArea": 54778611606,
"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
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,
"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.
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": "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
Note
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"
}
}
Note
To process a user-provided image (see Upload image section), set parameters as follows:
"params": {
"source_type": "local",
"url": "s3://users-data/user@email.com_eaf9e720-c6de-4d9b-8aec-52296d43f0c4/1e7fc660-7d0a-4632-9e6c-e95cf20e62b9/b97e9154-a356-450c-990b-fb1692d404ec.tif"
}
Response: the newly created processing.
✍️ 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. |
|
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 |
|
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.
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
Note
❗️ Use Mapflow Data API to create a mosaic and upload one or more images
Use s3 link from the
"image_url"as an"url"param to Run the processing
Error messages in API
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 |