Refactor API documentation and parameters for clarity and consistency

.python-version

@@ -0,0 +1 @@
+3.10

README.md

@@ -4,6 +4,18 @@
 
 Before start you need to install the required dependencies
 
+## Prerequisites
+
+- Python 3.10
+- uv
+
+`uv` is a fast Python package manager and virtual environment tool (by Astral).
+Install it with one of the following:
+
+    pipx install uv
+    # or
+    python -m pip install uv
+
 ### If this is your first time using this project
 
 Create venv:
@@ -14,7 +26,11 @@ Activate the `.venv`:
 
     source .venv/bin/activate
 
-Install requirements:
+Install requirements (recommended):
+
+    uv pip install -r requirements.txt
+
+If you do not have `uv` installed, use:
 
     pip3 install -r requirements.txt
 
@@ -24,6 +40,10 @@ Just activate `.venv`:
 
     source .venv/bin/activate
 
+Ensure dependencies are up to date:
+
+    uv pip install -r requirements.txt
+
 **Then you can run Sphinx commands.**
 
 ## Build
@@ -71,13 +91,10 @@ sphinx-intl update -p build/gettext -l ru
 
 ## Using autobuild
 
-To watch docs changes immediately you can use sphinx-autobuild tool
-
-Install sphinx-autobuild:
-
-    pip3 install sphinx-autobuild
+To watch docs changes immediately you can use sphinx-autobuild tool.
+It is included in `requirements.txt`.
 
-Run the autobuild server
+Run the autobuild server:
 
     sphinx-autobuild source build/autobuild
 

requirements.txt

@@ -33,3 +33,4 @@ sphinxcontrib-serializinghtml==1.1.5
 sphinxnotes-strike==1.2
 urllib3==1.26.7
 zipp==3.6.0
+sphinx-autobuild==2024.10.3

source/api/_static/csv/params_ds.csv

@@ -1,10 +1,14 @@
-Params,Type,Description,Sample values
-name,String,Name of the featured data  provider if its available for the current account. ,"1) ""Mapbox""
-2) ""arcgis_world_imagery""
-3) ""Global mosaic 2022"""
-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","1) ""XYZ""
-2) ""TMS""
-3) ""local"""
-zoom,String,Zoom level,"""18"""
+Params,Type,Description,Sample values
+sourceParams.dataProvider.providerName,String,"Name of linked data provider.","Mapbox"
+sourceParams.dataProvider.zoom,Integer,"Zoom level (optional).","18"
+sourceParams.userDefined.url,String,"Custom tile URL.","https://my-tiles/{z}/{x}/{y}.png"
+sourceParams.userDefined.sourceType,String,"XYZ | TMS | QUADKEY | SENTINEL_L2A | LOCAL","XYZ"
+sourceParams.userDefined.zoom,Integer,"Zoom level (optional).","19"
+sourceParams.userDefined.crs,String,"CRS code (optional).","EPSG:3857"
+sourceParams.userDefined.rasterLogin,String,"Raster auth username (optional).","user"
+sourceParams.userDefined.rasterPassword,String,"Raster auth password (optional).","pass"
+sourceParams.myImagery.imageIds,Array,"List of Mapflow image IDs.","[\"uuid\"]"
+sourceParams.myImagery.mosaicId,String,"Optional mosaic ID.","uuid"
+sourceParams.imagerySearch.dataProvider,String,"Imagery provider code.","orbview"
+sourceParams.imagerySearch.imageIds,Array,"List of imagery IDs.","[\"id\"]"
+sourceParams.imagerySearch.zoom,Integer,"Zoom level (optional).","18"

source/api/_static/csv/params_run.csv

@@ -1,9 +1,15 @@
-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
+Params,Type,Description
+geometry*,Object,"Processing area in GeoJSON format (Polygon or MultiPolygon)."
+name,String,"Processing name (optional)."
+description,String,"Processing description (optional)."
+projectId,String,"Project ID (optional). If omitted, default project is used."
+wdId / wdName,String,"Workflow definition ID or name (provide one)."
+params,Object,"Processing parameters."
+params.sourceParams,Object,"Data source parameters (required when params is provided)."
+params.sourceParams.dataProvider,Object,"Use a linked data provider."
+params.sourceParams.imagerySearch,Object,"Use imagery search results."
+params.sourceParams.myImagery,Object,"Use images or mosaic from Mapflow storage."
+params.sourceParams.userDefined,Object,"Use a custom imagery source."
+params.inferenceParams,Object,"Model-specific inference parameters."
+blocks,Array,"Model options to enable/disable."
+meta,Object,"Optional metadata key-value map."

source/api/data_api.rst

@@ -26,9 +26,9 @@ Manage Imagery Mosaics
 Create mosaic
 ^^^^^^^^^^^^^^^
 
-``POST https://api.mapflow.ai/rest/rasters/mosaic`` 
+``POST https://api.mapflow.ai/rest/rasters/mosaic``
 
-Creates the mosaic (the empty collection of images) and returns its ID.
+Creates an empty mosaic and returns its ID.
 
 .. code:: bash
 
@@ -57,7 +57,7 @@ Create mosaic and upload images to mosaic
 Get mosaic
 ^^^^^^^^^^^^^^^
 
-``GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}`` 
+``GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}``
 
 
 Update mosaic
@@ -112,7 +112,7 @@ Response example:
 Get images by mosaic ID
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}\image``
+``GET https://api.mapflow.ai/rest/rasters/mosaic/{mosaic_id}/image``
 
 Response example:
 
@@ -181,7 +181,7 @@ Delete image
 Get image preview
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``GET https://api.mapflow.ai/rest/rasters/{image_id}/preview/{preview_type}``
+``GET https://api.mapflow.ai/rest/rasters/image/{image_id}/preview/{preview_type}``
 
 E.g.:
 
@@ -234,7 +234,7 @@ This method allows to check user's storage usage against the available limit.
 Get metadata of available images
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-``POST https://api.mapflow.ai/catalog/meta``
+``POST https://api.mapflow.ai/rest/catalog/meta``
 
 
 Returns a list of the available images, filtered by metadata keys. 
@@ -271,15 +271,22 @@ Pagination and sorting options are also available:
 
 .. note::
 
-   | ``aoi``: geometry, - required, Geojson-like Polygon or Multipolygon of the area of the search
-   | ``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 – minimum intersection of the image footprint with the aoi
+   | ``aoi``: geometry (required), GeoJSON Polygon or MultiPolygon of the search area
+   | ``acquisitionDateFrom``: UTC date-time string
+   | ``acquisitionDateTo``: UTC date-time string
+   | ``minResolution``: float, meters per pixel
+   | ``maxResolution``: float, meters per pixel
+   | ``maxCloudCover``: float, percent (0-1)
+   | ``minOffNadirAngle``: float, degrees
+   | ``maxOffNadirAngle``: float, degrees
+   | ``minAoiIntersectionPercent``: float, percent (0-1) minimum footprint overlap
+   | ``limit``: integer, max number of results
+   | ``offset``: integer, pagination offset
+   | ``hideUnavailable``: boolean, exclude unavailable products
+   | ``dataProviders``: array of provider IDs/names
+   | ``productTypes``: array of product types (e.g. Scene, Mosaic)
+   | ``sortBy``: string field name
+   | ``sortOrder``: string (e.g. asc, desc)
 
 .. warning::
     The size of the search area cannot exceed the size of AOI limit assigned to the specific user.
@@ -365,8 +372,17 @@ Run processing by image ID
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For detailed description how to run a processing with Mapflow API see :doc:`Mapflow Processing API <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>}}``
+To run a processing using the specific image returned by Search API, pass the provider and image ID in v2 parameters:
 
+.. code:: json
 
+    {
+      "params": {
+        "sourceParams": {
+          "imagerySearch": {
+            "dataProvider": "<providerName>",
+            "imageIds": ["<imageId>"]
+          }
+        }
+      }
+    }