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

Open the web application Mapflow. Register a new account or sign in using your Google account.
Go to user profile settings to generate a new API token.

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

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 linked to the default data providers, yet specific commercial providers 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,
    "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": "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": "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

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.

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

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}, 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

Mapflow Data API

Note

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

Link image to the existing mosaic

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

curl --location -g --request POST 'https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}/link-image' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR TOKEN>' \
--data-raw '{
"url": "s3://users-data/user@email.com_045b8085-0ab8-42dc-8c65-c366cbaab5e0/8b6e9f1e-8ee6-4c15-9b39-c3bd6431f3f6/cog/area-5911389.tif"
}'

Response example:

{
"message": "File successfully linked to a mosaic",
"mosaic_id": "6ee95ae6-f26e-41bd-8cb1-39bea545119f"
}

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:

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 imagery source and a Mapflow Processing API. The API returns the search results by the imagery providers linked to the specific user. If no provider is linked to the user it returns all providers available. To run the processing one needs to get the provider linked to his user account.

Get metadata of available images

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

type: application/json

Returns a list of the available images, filtered by metadata.

E.g.:

{
    "aoi": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    69.1618,
                    41.2105
                ],
                [
                    69.1618,
                    41.3784
                ],
                [
                    69.3716,
                    41.3784
                ],
                [
                    69.3716,
                    41.2105
                ],
                [
                    69.1618,
                    41.2105
                ]
            ]
        ]
    },
    "acquisitionDateFrom": "2023-10-01T00:00:00Z",
    "acquisitionDateTo": "2022-10-10T00:00:00Z",
    "maxCloudCover": 0.1,
    "maxResolution": 0.5,
    "minResolution": 0.3
}

Response example:

{
    "images": [
        {
            "id": "JL1GF03D15_PMS_20230913140838_200196307_108_0001_001_L1",
            "footprint": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [
                            69.2325,
                            41.5352
                        ],
                        [
                            69.3602,
                            41.5151
                        ],
                        [
                            69.3182,
                            41.3647
                        ],
                        [
                            69.1906,
                            41.3848
                        ],
                        [
                            69.2325,
                            41.5352
                        ]
                    ]
                ]
            },
            "pixelResolution": 0.0,
            "acquisitionDate": "2023-09-13T14:08:40Z",
            "productType": "A",
            "sensor": "JL1GF03D15",
            "colorBandOrder": "unknown",
            "cloudCover": 0.0,
            "offNadirAngle": -12.49,
            "previewType": "png",
            "previewUrl": "https://home.sat-imagery.com/geoserver/rs_data/wms?SERVICE=WMS&VERSION=1.1.0&REQUEST=GetMap&FORMAT=image%2Fpng&TRANSPARENT=true&LAYERS=rs_data%3AJL1GF03D15_PMS_20230913140838_200196307_108_0001_001_L1&STYLES=&serverType=geoserver&crossOrigin=anonymous&tiled=false&angle=0&WIDTH=188&HEIGHT=253&SRS=EPSG%3A3857&BBOX=7702262.3596810745%2C5066284.571753241%2C7721142.145319615%2C5091606.951481916",
            "providerName": "sat_imagery"
        }
    ]
}

Note

aoi: geometry, - required, Geojson-like Polygon or Multipolygon
acquisitionDateFrom: UTC time string
acquisitionDateTo: UTC time string
minResolution: float, in meters
maxResolution: float, in meters
maxCloudCover: float, in percents
minOffNadirAngle: float, in degrees
maxOffNadirAngle: float, in degrees
minAoiIntersectionPercent: float, in percents

Warning

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

Run processing by image ID

For detailed description how to run a processing with Mapflow API see Mapflow Processing API – “Create processing”. To run a processing using the specific image returned by Search API define provider and image ID in the params as follows:

{"params": {"data_provider":<providerName>, "url":<id>}}