From bc69777bf54bc80fa23f951cf0ad3a9adc03fa03 Mon Sep 17 00:00:00 2001 From: Aimee Barciauskas Date: Tue, 16 Jan 2024 10:04:44 -0800 Subject: [PATCH 1/3] Create API.md --- API.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 API.md diff --git a/API.md b/API.md new file mode 100644 index 00000000..e4cb64c5 --- /dev/null +++ b/API.md @@ -0,0 +1,67 @@ +# API Specification + +## API Specification for /tiles/x/y/z Endpoint + +## Endpoint Description + +`GET /tiles/{x}/{y}/{z}` + +This endpoint provides tiled data for specific geographical locations and times. Tiles are defined by their x, y, and z coordinates. + +## Parameters + +- **Path Parameters:** + - `x` (integer): The x coordinate of the tile. + - `y` (integer): The y coordinate of the tile. + - `z` (integer): The zoom level of the tile. + +- **Query Parameters:** + - `collection_concept_id` (string, required): The concept ID of the collection. + - `variable` (string, required): The variable of interest. + - `timestamp` (string, required): The time for which data is requested, in ISO 8601 format. + - `colormap` (string, optional): The name of the colormap to apply. + - `rescale` (string, optional): The rescale range in the format `min,max`. + +## Request Example + +GET /tiles/1/2/3?collection_concept_id=C0000000000-YOCLOUD&variable=temperature×tamp=2024-01-16T00:00:00Z&colormap=viridis&rescale=0,100 + + +## Responses + +- **200 OK:** + - Description: Successful response with tile data. + - Content type: `image/png` + - Body: [Binary Data] + +- **400 Bad Request:** + - Description: The request is invalid. This can happen with missing required parameters or invalid parameter values. + - Content type: `application/json` + - Body: + ```json + { + "error": "Invalid request parameters." + } + ``` + +- **404 Not Found:** + - Description: No data found for the specified parameters. + - Content type: `application/json` + - Body: + ```json + { + "error": "No data found for the provided coordinates and time." + } + ``` + +- **500 Internal Server Error:** + - Description: Generic server error message for when an error has occurred on the server. + - Content type: `application/json` + - Body: + ```json + { + "error": "Internal server error." + } + ``` + + From 1a9164e6ddee4538d7e9528ce9fc80ec3e679603 Mon Sep 17 00:00:00 2001 From: vincentsarago Date: Wed, 17 Jan 2024 13:48:08 +0100 Subject: [PATCH 2/3] update from main --- docs/mkdocs.yml | 1 + API.md => docs/src/API.md | 0 2 files changed, 1 insertion(+) rename API.md => docs/src/API.md (100%) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index faa25155..771c43e6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -19,6 +19,7 @@ extra: nav: - Home: index.md + - API: API.md - Development - Contributing: contributing.md - Release notes: release-notes.md - Performance Benchmarks: benchmark.html diff --git a/API.md b/docs/src/API.md similarity index 100% rename from API.md rename to docs/src/API.md From 67b52d0145930b8d209de7e7b30a03d3fcf676f3 Mon Sep 17 00:00:00 2001 From: vincentsarago Date: Tue, 6 Feb 2024 15:58:59 +0100 Subject: [PATCH 3/3] update docs --- docs/src/API.md | 47 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/docs/src/API.md b/docs/src/API.md index e4cb64c5..62ce4050 100644 --- a/docs/src/API.md +++ b/docs/src/API.md @@ -4,27 +4,54 @@ ## Endpoint Description -`GET /tiles/{x}/{y}/{z}` +`GET /collections/{collectionId}/tiles/{tileMatrixSetId}/{z}/{x}/{y}@{scale}x` + +`GET /collections/{collectionId}/tiles/{tileMatrixSetId}/{z}/{x}/{y}@{scale}x.{format}` + +`GET /collections/{collectionId}/tiles/{tileMatrixSetId}/{z}/{x}/{y}.{format}` + +`GET /collections/{collectionId}/tiles/{tileMatrixSetId}/{z}/{x}/{y}` This endpoint provides tiled data for specific geographical locations and times. Tiles are defined by their x, y, and z coordinates. ## Parameters - **Path Parameters:** - - `x` (integer): The x coordinate of the tile. - - `y` (integer): The y coordinate of the tile. - - `z` (integer): The zoom level of the tile. + - `collectionId` (string): The [concept ID](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html#c-concept-id) of the collection. + - `tileMatrixSetId` (string): TileMatrixSet name (e.g **WebMercatorQuad**) + - `x` (integer): The x coordinate of the tile + - `y` (integer): The y coordinate of the tile + - `z` (integer): The zoom level of the tile + - `scale` (integer, optional): Tile size scale, default is set to 1 (256x256) + - `format` (string, optional): Output image format, default is set to None and will be either JPEG or PNG depending on the presence of masked value. - **Query Parameters:** - - `collection_concept_id` (string, required): The concept ID of the collection. - - `variable` (string, required): The variable of interest. - - `timestamp` (string, required): The time for which data is requested, in ISO 8601 format. - - `colormap` (string, optional): The name of the colormap to apply. - - `rescale` (string, optional): The rescale range in the format `min,max`. + - `temporal` (string, optional): Either a date-time or an interval. Date and time expressions adhere to 'YYYY-MM-DD' format. Intervals may be bounded or half-bounded (double-dots at start or end) **RECOMMENDED** + - `backend` (*cog* or *xarray*, optional): Backend to use in order to read the CMR dataset. Defaults to `cog` + - `variable`* (string, optional): The variable of interest. `required` when using `xarray` backend + - `time_slice`* (string, optional): The time for which data is requested, in ISO 8601 format + - `decode_times`* (bool, optional): Whether to decode times + - `bidx`** (int, optional): Dataset band indexes (multiple allowed) + - `expression`** (string, optional): rio-tiler's band math expression + - `unscale`** (bool, optional): Apply dataset internal Scale/Offset. + - `nodata` (string or number, optional): Overwrite internal Nodata value + - `resampling`**: RasterIO resampling algorithm. Defaults to `nearest`. + - `reproject`: WarpKernel resampling algorithm (only used when doing re-projection). Defaults to `nearest`. + - `algorithm` (string, optional): Custom algorithm name (e.g hillshade). + - `algorithm_params` (string): JSON encoded algorithm parameters. + - `color_formula` (string): rio-color formula. + - `colormap_name` (string, optional): The name of the colormap to apply + - `colormap` (string, optional): JSON encoded custom Colormap + - `rescale` (string, optional): The rescale range in the format `min,max` + - `return_mask` (bool, optional): Add mask to the output data. Defaults to `True` + +\* used in `xarray` backend only + +\** used in `cog` backend only ## Request Example -GET /tiles/1/2/3?collection_concept_id=C0000000000-YOCLOUD&variable=temperature×tamp=2024-01-16T00:00:00Z&colormap=viridis&rescale=0,100 +GET /collections/C0000000000-YOCLOUD/tiles/WebMercatorQuad/1/2/3?backend=xarray&variable=temperature×tamp=2024-01-16T00:00:00Z&colormap=viridis&rescale=0,100&temporal=2024-01-16/2024-01-16 ## Responses