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 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 |
Mapflow Data 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 images, aimed at instant preview and processing. It’s helpful in such cases as collecting and mosaicing the number of single aerial images covering some area or batching the large orthomap 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"
]
}'
Create mosaic and upload images to mosaic
curl --location -g --request POST 'https://api.mapflow.ai/rest/rasters/mosaic/image?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"
}
Get images by mosaic ID
GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}\image
Response example:
[
{
"id": "6ae7f9e9-da2d-41e0-b16f-83396003af57",
"image_url": "s3://users-data/user@email.com_eaf9e720-c6de-4d9b-8aec-52296d43f0c4/90fe01b2-8c21-4d5b-9d4f-143b05d3e986/6ae7f9e9-da2d-41e0-b16f-83396003af57.tif",
"preview_url_l": "https://api.mapflow.ai/rest/rasters/image/6ae7f9e9-da2d-41e0-b16f-83396003af57/preview/l",
"preview_url_s": "https://api.mapflow.ai/rest/rasters/image/6ae7f9e9-da2d-41e0-b16f-83396003af57/preview/s",
"uploaded_at": "2023-01-26T13:58:32.122099",
"file_size": 68417439,
"footprint": "POLYGON ((1.991514383583533 48.76433046008412, 1.991514383583533 48.77553902852908, 1.968476220399751 48.77553902852908, 1.968476220399751 48.76433046008412, 1.991514383583533 48.76433046008412))",
"filename": "bd8b9969505748898adac2cfa80d3425.tif",
"checksum": "9d2d9e9bd347fc5204e5fd1add0982aadff21f17",
"meta_data": {
"crs": "EPSG:32631",
"count": 3,
"width": 5589,
"dtypes": [
"uint8",
"uint8",
"uint8"
],
"height": 4079,
"nodata": null,
"pixel_size": [
0.3000000000000021,
0.3000000000000457
]
},
"cog_link": "s3://users-data/user@email.com_eaf9e720-c6de-4d9b-8aec-52296d43f0c4/90fe01b2-8c21-4d5b-9d4f-143b05d3e986/cog/area-1101712.tif"
}
]
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 an early version of the Mapflow unified 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 for the imagery providers linked to the specific Mapflow user. If no provider is linked to the user it returns all providers results available. But to run the processing the user needs to get the provider linked to his account.
Get metadata of available images
POST https://api.mapflow.ai/catalog/meta
Returns a list of the available images, filtered by metadata keys.
E.g. request:
curl --location 'https://api.mapflow.ai/rest/catalog/meta' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ******' \
--data '{
"aoi": {
"type": "Polygon",
"coordinates": [[[76.6755,43.2234],[76.6755,43.4712],[77.0163,43.4712],[77.0163,43.2234],[76.6755,43.2234]]]
},
"acquisitionDateFrom": "2022-04-01T00:00:00Z",
"acquisitionDateTo": "2022-11-01T00:00:00Z",
"maxCloudCover": 0.1,
"maxResolution": 0.5,
"minResolution": 0.3
}'
Note
aoi: geometry, - required, Geojson-like Polygon or Multipolygon of the area of the searchacquisitionDateFrom: UTC time stringacquisitionDateTo: UTC time stringminResolution: float, in metersmaxResolution: float, in metersmaxCloudCover: float, in percentsminOffNadirAngle: float, in degreesmaxOffNadirAngle: float, in degreesminAoiIntersectionPercent: float, in percents – minimum intersection of the image footprint with the aoiWarning
The size of the search area cannot exceed the size of AOI limit assigned to the specific user.
Response example – Scene:
{
"id": "JL1GF03A_PMS_20220607132729_200087596_103_0002_001_L1",
"footprint": {
"type": "Polygon",
"coordinates": [
[
[
76.5009,
43.3412
],
...
]
]
},
"pixelResolution": 1.06,
"acquisitionDate": "2022-06-07T13:27:33Z",
"productType": "Scene",
"sensor": "JL1GF03A",
"colorBandOrder": "B,G,R,NIR,PAN",
"cloudCover": 0.09,
"offNadirAngle": -3.91,
"previewType": "png",
"previewUrl": "https://cgwx-jpg.obs.cn-north-4.myhuaweicloud.com:443/thumbnail_mss/JL1GF03A_PMS_20220607132729_200087596_103_0002_001_L1.jpg",
"providerName": "CG"
}
Response example – Mosaic:
{
"id": "JL1KF01A_PMS04_20220717131252_200093089_101_0005_001_L1",
"footprint": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
76.903651508,
43.252856702
],
...
]
]
]
},
"pixelResolution": 0.0,
"acquisitionDate": "2022-07-17T00:00:00Z",
"productType": "Mosaic",
"sensor": "JL1KF01A",
"colorBandOrder": "RGB",
"cloudCover": 0.0,
"offNadirAngle": 3.0,
"previewType": "xyz",
"previewUrl": "https://app.mapflow.ai/tiles/charmingglobe/{z}/{x}/{-y}.png?year=2022",
"providerName": "CG_mosaic_2022"
}
Note
There are two types of products in the Imagery Search API available: 1. The Scene product is available for ordering by request. Now you need to contact us to order the specific image. 2. The Mosaic product is available for instant analysis if the corresponding data provider is linked to your Mapflow account.
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>}}