Mapflow API

Authorization to Mapflow API

To access from external applications such as plugin for QGIS you need to get API token. Users can register and obtain token at https://app.mapflow.ai/account/api. Token must be passed in the Basic Auth parameters like in the example:

curl --location --request GET 'https://api.mapflow.ai/rest/projects/default' \
--header 'Authorization: Basic <YOUR TOKEN>'

Note

Your token is generated by request and composed of <Email: API Token>

You can decode it with base64 decoder to use in Basic Auth form

Make sure you save the token, otherwise you will need to reissue it.

Obtaining an API token

  1. Open the web application Mapflow. Register a new account or sign in using your Google account.

  2. Go to user profile settings to generate a new API token.

Preview map

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

Mapflow Data API

Note

Preview results

Check and run this Postman collection for API.

Note

Data API allows to manage your imagery, organise it into collections (mosaics), reuse for processings with Mapflow and preview them as XYZ layers. 👉 To use the imagery processing API see this documentation

Manage Imagery Mosaics

Note

What is “mosaic”? This is the collection of single images, aimed at instant preview and processing. It’s helpful in such cases as mosaicing the number of single aerial images covering some area or batching the large ortho-plan for faster uploading and optimizing its storage in the cloud.

Create mosaic

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

Creates the mosaic (the empty collection of images) and returns its ID.

curl --location --request POST 'https://api.mapflow.ai/rest/rasters/mosaic' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--data-raw '{
"name": "mosaic-name",
"tags": [
    "tag-1",
    "tag-2"
    ]
}'

Creates mosaic and uploads images to the mosaic

curl --location -g --request POST 'https://api.mapflow.ai/rest/rasters/mosaic/mosaic?name={name}&tags={tag1}&tags={tag2}' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--form 'file=@"/path/to/file"'

Get mosaic

GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}

Update mosaic

curl --location --request PUT 'https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--data-raw '{
"name": "new-mosaic-name",
"tags": [
    "new-tag-1",
    "new-tag-2"
    ]
}'

Upload images to the existing mosaic

Attention

⚠️ The uploaded images are required to have the same georeference system, number of bands, and spatial resolution.

POST https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}/image

Delete mosaic

Attention

Deleting mosaic also deletes all linked images and they cannot be restored

DELETE https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}

Manage Images

Get image metadata by image ID

GET https://api.mapflow.ai/rest/rasters/image/{image_id}

Delete image

DELETE https://api.mapflow.ai/rest/rasters/image/{image_id}

Get image preview

GET https://api.mapflow.ai/rest/rasters/{image_id}/preview/{preview_type}

E.g.:

curl --location --request GET 'https://api.mapflow.ai/rest/rasters/image/{image_id}/preview/s' \
--header 'Content-Type: image/jpg' \
--header 'Authorization: Basic <YOUR TOKEN>'

Response example:

Image preview

PREVIEW TYPE

DESCRIPTION

s

image 256x256

l

image 1024x1024

Attention

Mapflow Storage

Get user’s storage limits

GET https://api.mapflow.ai/rest/rasters/memory

This method allows to check user’s storage usage against the available limit.

Search Imagery

Note

This is the early version of the Mapflow API to search for available satellite images provided by external data providers. The API aims to perform as a middle-tear between multiple data source and a Mapflow Processing API.

Get metadata of available images

POST https://api.mapflow.ai/catalog/meta

Returns a list of the images in GeoJSON, filtered by metadata. E.g.:

{ "aoi": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              37.34396696090698,
              55.6731196654679
            ],
            [
              37.35926628112793,
              55.6731196654679
            ],
            [
              37.35926628112793,
              55.67997991819218
            ],
            [
              37.34396696090698,
              55.67997991819218
            ],
            [
              37.34396696090698,
              55.6731196654679
            ]
          ]
        ]
    },
  "acquisitionDateFrom": "2021-01-01T00:00:00Z",
  "acquisitionDateTo": "2022-01-01T00:00:00Z",
  "maxCloudCover": 0.1,
  "maxResolution": 0.31,
  "minResolution": 0.3
}

Response example:

{ "images": [
        {
            "id": "a518230a236664891bfb2d8041028a59",
            "footprint": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            37.2883723,
                            55.96500262
                        ],
                        [
                            37.3950109,
                            55.96416162
                        ],
                        [
                            37.50164951,
                            55.96332062
                        ],
                        [
                            37.50141629,
                            55.72561772
                        ],
                        [
                            37.50118307,
                            55.48791481
                        ],
                        [
                            37.39506886,
                            55.48708936
                        ],
                        [
                            37.28895464,
                            55.48626391
                        ],
                        [
                            37.28866347,
                            55.72563326
                        ],
                        [
                            37.2883723,
                            55.96500262
                        ]
                    ]
                ]
            },
            "pixelResolution": 0.31,
            "acquisitionDate": "2021-07-07T08:42:03Z",
            "productType": "Pan Sharpened Natural Color",
            "sensor": "WV03_VNIR",
            "colorBandOrder": "RGB",
            "cloudCover": 0.0,
            "offNadirAngle": 6.471679
        }
    ]
}

aoi (required) - the geometry of the area (GeoJSON, Lat Lon coordinates) to search imagery for. Currently the only type Polygon is supported.

Important

The size of the area cannot exceed the size of processing AOI limit assigned to the specific user.

acquisitionDateFrom <> acquisitionDateTo (optional) - date/time format in UTC time zone according to ISO-8601. Determines the time range that the imagery acquisition date corresponds to.

maxCloudCover (optional) - maxCloudCover — optional, a decimal number in the range 0 - 1 (corresponds to 0-100% cloud coverage). This parameter defines the maximum area of an image (in pixels) that was classified as covered by clouds.

maxResolution - optional, defines the maximum allowed resolution in m / pixel

minResolution - optional, defines the minimum allowed resolution in m / pixel

Get metadata by image ID

GET https://api.mapflow.ai/rest/catalog/meta/{image_id}

curl --location --request GET 'https://api.mapflow.ai/rest/catalog/meta/{image_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>'

You can get image_id from processing.params.url