From 3b87dd7511369385259b61d0d698be51948b0a15 Mon Sep 17 00:00:00 2001 From: jklaer Date: Fri, 23 Jan 2026 16:58:25 +0100 Subject: [PATCH 1/7] Add API examples and usage patterns for STAC Atlas --- api/docs/api-examples.md | 193 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 api/docs/api-examples.md diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md new file mode 100644 index 0000000..abd1f31 --- /dev/null +++ b/api/docs/api-examples.md @@ -0,0 +1,193 @@ + +# STAC Atlas API – Beispielanfragen & Suchmuster + +Diese Datei zeigt, wie du die wichtigsten Endpunkte der STAC Atlas API mit curl testen kannst. Sie enthält praktische Beispiele für Suchanfragen, Filter, Paging und Fehlerfälle. Alle Beispiele gehen davon aus, dass dein Server lokal unter http://localhost:3000 läuft. + +--- + +## curl-Beispiele für alle Endpunkte + +### Landing Page (API-Root) +Zeigt Basisinformationen und Links zu weiteren Endpunkten. + +### Landing Page +```bash +curl -X GET "http://localhost:3000/" -H "accept: application/json" +``` + +### Conformance +Listet die unterstützten OGC/STAC-Konformitätsklassen auf. +```bash +curl -X GET "http://localhost:3000/conformance" -H "accept: application/json" +``` + +### Collections (mit Parametern) +Gibt eine Liste von Collections zurück. Mit Parametern kannst du die Suche filtern. +```bash +curl -X GET "http://localhost:3000/collections?limit=5&q=landsat" -H "accept: application/json" +``` + +### Einzelne Collection +Gibt die Metadaten einer bestimmten Collection (z.B. "vegetation") zurück. +```bash +curl -X GET "http://localhost:3000/collections/vegetation" -H "accept: application/json" +``` + +### Queryables +Zeigt, welche Felder für Filter und Sortierung verwendet werden können. +```bash +curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" +``` + +--- + +## CQL2-Filter-Beispiele + +CQL2 ist eine mächtige Sprache für komplexe Filter. Die API unterstützt sowohl CQL2-Text als auch CQL2-JSON. + +### CQL2-Text +CQL2-Text ist menschenlesbar und eignet sich für einfache bis mittlere Filter. +- Lizenzfilter: + ```bash + curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" + ``` +- Titel exakt "Sentinel-2 L2A": + ```bash + curl "http://localhost:3000/collections?filter=title%20%3D%20'Sentinel-2%20L2A'" + ``` +- Titel ist einer von mehreren: + ```bash + curl "http://localhost:3000/collections?filter=title%20IN%20('Sentinel-2%20L2A','CHELSA%20Climatologies')" + ``` +- Kombinierte Filter: + ```bash + curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'%20AND%20id%20%3E%2010" + ``` + +- Mehrere Lizenzen (OR): + ```bash + curl "http://localhost:3000/collections?filter=license%20%3D%20'CC-BY-4.0'%20OR%20license%20%3D%20'MIT'" + ``` + +### CQL2-JSON +CQL2-JSON ist maschinenlesbar und besonders für komplexe, verschachtelte Filter und Geo-Objekte geeignet. +- Bounding Box (S_INTERSECTS): + ```bash + curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" + ``` +- Zeitintervall (T_INTERSECTS): + ```bash + curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" + ``` + +--- + +## Häufige Suchmuster + +Hier findest du typische Anwendungsfälle für die Suche, Paginierung und Sortierung. + +### Paging (Seitenweise Ergebnisse) +Hole dir große Ergebnislisten seitenweise ab. Die Links im Response helfen beim Blättern. +```bash +curl "http://localhost:3000/collections?limit=10&token=0" +curl "http://localhost:3000/collections?limit=10&token=10" +``` + +### Sortierung +Sortiere nach verschiedenen Feldern, z.B. nach Erstellungsdatum oder Titel. +```bash +curl "http://localhost:3000/collections?sortby=-created" +curl "http://localhost:3000/collections?sortby=title" +``` + +--- + +## Fehlerfälle + +- Ungültige Collection-ID: + ```bash + curl -X GET "http://localhost:3000/collections/doesnotexist" -H "accept: application/json" + ``` + _Response: 404 Not Found with error object._ + +- Ungültiger Parameter: + ```bash + curl "http://localhost:3000/collections?limit=abc" + ``` + _Response: 400 Bad Request with error description._ + +- Falsches Filterformat: + ```bash + curl "http://localhost:3000/collections?filter=license%20LIKE%20MIT" + ``` + _Response: 400 Bad Request (unsupported CQL2 operator)._ + +--- + +## Erweiterte Beispiele + +- CQL2-JSON: Kombinierter räumlicher und zeitlicher Filter + ```bash + curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22and%22%2C%22args%22%3A%5B%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D%2C%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D%5D%7D" + ``` + +- Freitextsuche mit Umlauten/Sonderzeichen (Münster): + ```bash + curl "http://localhost:3000/collections?q=M%C3%BCnster" + ``` + +- Nur bestimmte Felder anzeigen: + ```bash + curl -s "http://localhost:3000/collections?limit=1" + ``` + +--- + +## Queryables-Details prüfen + +Der Queryables-Endpunkt zeigt, welche Felder du für Filter und Sortierung nutzen kannst: +```bash +curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" +``` +_Response: JSON schema with all queryable properties._ + +--- + +## Header & Formate + +- Die API antwortet standardmäßig mit `application/json`. +- Für Queryables: `application/schema+json`. +- CORS ist aktiviert, sodass du auch aus dem Browser testen kannst. + +--- + +### Beispiel für eine erfolgreiche Collection-Suche +```bash +curl "http://localhost:3000/collections?limit=1&q=sentinel" +``` +_Response:_ +```json +{ + "collections": [ + { + "id": "sentinel-2-l2a", + "title": "Sentinel-2 L2A", + "description": "Multispectral satellite data...", + "license": "CC-BY-4.0", + "keywords": ["satellite", "sentinel", "multispectral"], + "extent": { + "spatial": { "bbox": [[-180, -90, 180, 90]] }, + "temporal": { "interval": [["2015-06-23T00:00:00Z", null]] } + } + // ... weitere Felder ... + } + ], + "links": [ /* ... */ ] +} +``` + +### Fehlerfall: Nicht unterstützte Filter-Syntax +```bash +curl "http://localhost:3000/collections?filter=title%20LIKE%20'%25landsat%25'" +``` +_Response: 400 Bad Request (unsupported CQL2 operator: LIKE)_ \ No newline at end of file From e08b3bfa1345d55f1de92a6d69214ab549189146 Mon Sep 17 00:00:00 2001 From: jklaer Date: Sat, 24 Jan 2026 12:17:57 +0100 Subject: [PATCH 2/7] Translate API examples documentation from German to English and removing error cases --- api/docs/api-examples.md | 106 ++++++++++++++------------------------- 1 file changed, 39 insertions(+), 67 deletions(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index abd1f31..4c02c12 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -1,14 +1,14 @@ -# STAC Atlas API – Beispielanfragen & Suchmuster +# STAC Atlas API – Example Requests & Search Patterns -Diese Datei zeigt, wie du die wichtigsten Endpunkte der STAC Atlas API mit curl testen kannst. Sie enthält praktische Beispiele für Suchanfragen, Filter, Paging und Fehlerfälle. Alle Beispiele gehen davon aus, dass dein Server lokal unter http://localhost:3000 läuft. +This file shows how to test the main endpoints of the STAC Atlas API using curl. It contains practical examples for search queries, filters, paging, and error cases. All examples assume your server is running locally at http://localhost:3000. --- -## curl-Beispiele für alle Endpunkte +## curl Examples for All Endpoints -### Landing Page (API-Root) -Zeigt Basisinformationen und Links zu weiteren Endpunkten. +### Landing Page (API Root) +Shows basic information and links to further endpoints. ### Landing Page ```bash @@ -16,85 +16,85 @@ curl -X GET "http://localhost:3000/" -H "accept: application/json" ``` ### Conformance -Listet die unterstützten OGC/STAC-Konformitätsklassen auf. +Lists the supported OGC/STAC conformance classes. ```bash curl -X GET "http://localhost:3000/conformance" -H "accept: application/json" ``` -### Collections (mit Parametern) -Gibt eine Liste von Collections zurück. Mit Parametern kannst du die Suche filtern. +### Collections (with parameters) +Returns a list of collections. You can filter the search with parameters. ```bash curl -X GET "http://localhost:3000/collections?limit=5&q=landsat" -H "accept: application/json" ``` -### Einzelne Collection -Gibt die Metadaten einer bestimmten Collection (z.B. "vegetation") zurück. +### Single Collection +Returns the metadata of a specific collection (e.g., "vegetation"). ```bash curl -X GET "http://localhost:3000/collections/vegetation" -H "accept: application/json" ``` ### Queryables -Zeigt, welche Felder für Filter und Sortierung verwendet werden können. +Shows which fields can be used for filtering and sorting. ```bash curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" ``` --- -## CQL2-Filter-Beispiele +## CQL2 Filter Examples -CQL2 ist eine mächtige Sprache für komplexe Filter. Die API unterstützt sowohl CQL2-Text als auch CQL2-JSON. +CQL2 is a powerful language for complex filters. The API supports both CQL2-Text and CQL2-JSON. ### CQL2-Text -CQL2-Text ist menschenlesbar und eignet sich für einfache bis mittlere Filter. -- Lizenzfilter: +CQL2-Text is human-readable and suitable for simple to medium filters. +- License filter: ```bash curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" ``` -- Titel exakt "Sentinel-2 L2A": +- Title exactly "Sentinel-2 L2A": ```bash curl "http://localhost:3000/collections?filter=title%20%3D%20'Sentinel-2%20L2A'" ``` -- Titel ist einer von mehreren: +- Title is one of several: ```bash curl "http://localhost:3000/collections?filter=title%20IN%20('Sentinel-2%20L2A','CHELSA%20Climatologies')" ``` -- Kombinierte Filter: +- Combined filters: ```bash curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'%20AND%20id%20%3E%2010" ``` -- Mehrere Lizenzen (OR): +- Multiple licenses (OR): ```bash curl "http://localhost:3000/collections?filter=license%20%3D%20'CC-BY-4.0'%20OR%20license%20%3D%20'MIT'" ``` ### CQL2-JSON -CQL2-JSON ist maschinenlesbar und besonders für komplexe, verschachtelte Filter und Geo-Objekte geeignet. +CQL2-JSON is machine-readable and especially suitable for complex, nested filters and geo-objects. - Bounding Box (S_INTERSECTS): ```bash curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" ``` -- Zeitintervall (T_INTERSECTS): +- Time interval (T_INTERSECTS): ```bash curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" ``` --- -## Häufige Suchmuster +## Common Search Patterns -Hier findest du typische Anwendungsfälle für die Suche, Paginierung und Sortierung. +Here you will find typical use cases for search, pagination, and sorting. -### Paging (Seitenweise Ergebnisse) -Hole dir große Ergebnislisten seitenweise ab. Die Links im Response helfen beim Blättern. +### Paging (Page-wise Results) +Retrieve large result lists page by page. The links in the response help you to navigate. ```bash curl "http://localhost:3000/collections?limit=10&token=0" curl "http://localhost:3000/collections?limit=10&token=10" ``` -### Sortierung -Sortiere nach verschiedenen Feldern, z.B. nach Erstellungsdatum oder Titel. +### Sorting +Sort by different fields, e.g., by creation date or title. ```bash curl "http://localhost:3000/collections?sortby=-created" curl "http://localhost:3000/collections?sortby=title" @@ -102,50 +102,28 @@ curl "http://localhost:3000/collections?sortby=title" --- -## Fehlerfälle +## Advanced Examples -- Ungültige Collection-ID: - ```bash - curl -X GET "http://localhost:3000/collections/doesnotexist" -H "accept: application/json" - ``` - _Response: 404 Not Found with error object._ - -- Ungültiger Parameter: - ```bash - curl "http://localhost:3000/collections?limit=abc" - ``` - _Response: 400 Bad Request with error description._ - -- Falsches Filterformat: - ```bash - curl "http://localhost:3000/collections?filter=license%20LIKE%20MIT" - ``` - _Response: 400 Bad Request (unsupported CQL2 operator)._ - ---- - -## Erweiterte Beispiele - -- CQL2-JSON: Kombinierter räumlicher und zeitlicher Filter +- CQL2-JSON: Combined spatial and temporal filter ```bash curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22and%22%2C%22args%22%3A%5B%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D%2C%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D%5D%7D" ``` -- Freitextsuche mit Umlauten/Sonderzeichen (Münster): +- Free text search with special characters (Münster): ```bash curl "http://localhost:3000/collections?q=M%C3%BCnster" ``` -- Nur bestimmte Felder anzeigen: +- Show only certain fields: ```bash curl -s "http://localhost:3000/collections?limit=1" ``` --- -## Queryables-Details prüfen +## Check Queryables Details -Der Queryables-Endpunkt zeigt, welche Felder du für Filter und Sortierung nutzen kannst: +The Queryables endpoint shows which fields you can use for filtering and sorting: ```bash curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" ``` @@ -153,15 +131,15 @@ _Response: JSON schema with all queryable properties._ --- -## Header & Formate +## Headers & Formats -- Die API antwortet standardmäßig mit `application/json`. -- Für Queryables: `application/schema+json`. -- CORS ist aktiviert, sodass du auch aus dem Browser testen kannst. +- The API responds by default with `application/json`. +- For Queryables: `application/schema+json`. +- CORS is enabled, so you can also test from the browser. --- -### Beispiel für eine erfolgreiche Collection-Suche +### Example of a successful collection search ```bash curl "http://localhost:3000/collections?limit=1&q=sentinel" ``` @@ -179,15 +157,9 @@ _Response:_ "spatial": { "bbox": [[-180, -90, 180, 90]] }, "temporal": { "interval": [["2015-06-23T00:00:00Z", null]] } } - // ... weitere Felder ... + // ... more fields ... } ], "links": [ /* ... */ ] } ``` - -### Fehlerfall: Nicht unterstützte Filter-Syntax -```bash -curl "http://localhost:3000/collections?filter=title%20LIKE%20'%25landsat%25'" -``` -_Response: 400 Bad Request (unsupported CQL2 operator: LIKE)_ \ No newline at end of file From 80797417107bfb67e1689987afbee209269fc3d4 Mon Sep 17 00:00:00 2001 From: jklaer Date: Sat, 24 Jan 2026 13:59:13 +0100 Subject: [PATCH 3/7] Refactor API examples documentation for clarity and organization --- api/docs/api-examples.md | 148 +++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 70 deletions(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index 4c02c12..546e36d 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -5,39 +5,61 @@ This file shows how to test the main endpoints of the STAC Atlas API using curl. --- -## curl Examples for All Endpoints +## Headers & Formats -### Landing Page (API Root) -Shows basic information and links to further endpoints. +- The API responds by default with `application/json`. +- For Queryables: `application/schema+json`. +- CORS is enabled, so you can also test from the browser. + +--- + +## How to Use curl with This API + +To access any endpoint, simply use: -### Landing Page ```bash -curl -X GET "http://localhost:3000/" -H "accept: application/json" +curl "" ``` -### Conformance -Lists the supported OGC/STAC conformance classes. +Replace `` with the desired endpoint from the list below. For example, to get the landing page, use: + ```bash -curl -X GET "http://localhost:3000/conformance" -H "accept: application/json" +curl "http://localhost:3000/" ``` +--- + +## API Endpoints + +### Landing Page (API Root) +Shows basic information and links to further endpoints. + +"http://localhost:3000/" + +### Conformance +Lists the supported OGC/STAC conformance classes. + +"http://localhost:3000/conformance" + +### Collections +Returns a list of all collections. + +"http://localhost:3000/collections" + ### Collections (with parameters) Returns a list of collections. You can filter the search with parameters. -```bash -curl -X GET "http://localhost:3000/collections?limit=5&q=landsat" -H "accept: application/json" -``` + +"http://localhost:3000/collections?limit=5&q=landsat" ### Single Collection Returns the metadata of a specific collection (e.g., "vegetation"). -```bash -curl -X GET "http://localhost:3000/collections/vegetation" -H "accept: application/json" -``` + +"http://localhost:3000/collections/vegetation" ### Queryables Shows which fields can be used for filtering and sorting. -```bash -curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" -``` + +"http://localhost:3000/queryables" --- @@ -48,37 +70,35 @@ CQL2 is a powerful language for complex filters. The API supports both CQL2-Text ### CQL2-Text CQL2-Text is human-readable and suitable for simple to medium filters. - License filter: - ```bash - curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" - ``` + + "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" + - Title exactly "Sentinel-2 L2A": - ```bash - curl "http://localhost:3000/collections?filter=title%20%3D%20'Sentinel-2%20L2A'" - ``` + + "http://localhost:3000/collections?filter=title%20%3D%20'Sentinel-2%20L2A'" + - Title is one of several: - ```bash - curl "http://localhost:3000/collections?filter=title%20IN%20('Sentinel-2%20L2A','CHELSA%20Climatologies')" - ``` + + "http://localhost:3000/collections?filter=title%20IN%20('Sentinel-2%20L2A','CHELSA%20Climatologies')" + - Combined filters: - ```bash - curl "http://localhost:3000/collections?filter=license%20%3D%20'MIT'%20AND%20id%20%3E%2010" - ``` - + + "http://localhost:3000/collections?filter=license%20%3D%20'MIT'%20AND%20id%20%3E%2010" + - Multiple licenses (OR): - ```bash - curl "http://localhost:3000/collections?filter=license%20%3D%20'CC-BY-4.0'%20OR%20license%20%3D%20'MIT'" - ``` + + "http://localhost:3000/collections?filter=license%20%3D%20'CC-BY-4.0'%20OR%20license%20%3D%20'MIT'" + ### CQL2-JSON CQL2-JSON is machine-readable and especially suitable for complex, nested filters and geo-objects. - Bounding Box (S_INTERSECTS): - ```bash - curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" - ``` + + "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" + - Time interval (T_INTERSECTS): - ```bash - curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" - ``` + + "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" --- @@ -88,61 +108,49 @@ Here you will find typical use cases for search, pagination, and sorting. ### Paging (Page-wise Results) Retrieve large result lists page by page. The links in the response help you to navigate. -```bash -curl "http://localhost:3000/collections?limit=10&token=0" -curl "http://localhost:3000/collections?limit=10&token=10" -``` + +"http://localhost:3000/collections?limit=10&token=0" + +"http://localhost:3000/collections?limit=10&token=10" + ### Sorting Sort by different fields, e.g., by creation date or title. -```bash -curl "http://localhost:3000/collections?sortby=-created" -curl "http://localhost:3000/collections?sortby=title" -``` + +"http://localhost:3000/collections?sortby=-created" + +"http://localhost:3000/collections?sortby=title" --- ## Advanced Examples - CQL2-JSON: Combined spatial and temporal filter - ```bash - curl "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22and%22%2C%22args%22%3A%5B%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D%2C%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D%5D%7D" - ``` + + "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22and%22%2C%22args%22%3A%5B%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D%2C%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D%5D%7D" - Free text search with special characters (Münster): - ```bash - curl "http://localhost:3000/collections?q=M%C3%BCnster" - ``` + + "http://localhost:3000/collections?q=M%C3%BCnster" - Show only certain fields: - ```bash - curl -s "http://localhost:3000/collections?limit=1" - ``` + + "http://localhost:3000/collections?limit=1" --- ## Check Queryables Details The Queryables endpoint shows which fields you can use for filtering and sorting: -```bash -curl -X GET "http://localhost:3000/queryables" -H "accept: application/schema+json" -``` -_Response: JSON schema with all queryable properties._ - ---- -## Headers & Formats - -- The API responds by default with `application/json`. -- For Queryables: `application/schema+json`. -- CORS is enabled, so you can also test from the browser. +"http://localhost:3000/queryables" --- ### Example of a successful collection search -```bash -curl "http://localhost:3000/collections?limit=1&q=sentinel" -``` + +"http://localhost:3000/collections?limit=1&q=sentinel" + _Response:_ ```json { From 829a9d51d8fc6a36f3e15654c16c240a5bb53d09 Mon Sep 17 00:00:00 2001 From: jklaer Date: Sat, 24 Jan 2026 19:16:49 +0100 Subject: [PATCH 4/7] Enhance API examples documentation with detailed usage patterns for sorting and pagination aswell as further things on curl usage --- api/docs/api-examples.md | 55 +++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index 546e36d..1f9e183 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -15,13 +15,16 @@ This file shows how to test the main endpoints of the STAC Atlas API using curl. ## How to Use curl with This API -To access any endpoint, simply use: +`curl` is a widely used command-line tool for making HTTP requests to web servers and APIs. It is available by default on most Unix-based systems (Linux, macOS) and can be installed on Windows. With `curl`, you can retrieve data, test endpoints, and inspect API responses directly from your terminal. + +To interact with this API, open your terminal or command prompt and enter the following command, replacing `` with the desired endpoint from the list below: ```bash curl "" ``` -Replace `` with the desired endpoint from the list below. For example, to get the landing page, use: +This will send a GET request to the specified endpoint and print the server's response (usually in JSON format) to your terminal. +For example, to retrieve the landing page, use: ```bash curl "http://localhost:3000/" @@ -52,8 +55,9 @@ Returns a list of collections. You can filter the search with parameters. "http://localhost:3000/collections?limit=5&q=landsat" ### Single Collection -Returns the metadata of a specific collection (e.g., "vegetation"). +To retrieve the metadata of a specific collection, use the endpoint `/collections/{id}` where `{id}` is the STAC ID string of the desired collection. Replace `{id}` with the actual collection identifier (e.g., `vegetation`). +For example: "http://localhost:3000/collections/vegetation" ### Queryables @@ -63,6 +67,28 @@ Shows which fields can be used for filtering and sorting. --- +## Common Search Patterns + +Here you will find typical use cases for sorting and pagination. + +### Sorting +Sort by different fields, e.g., by creation date or title. +Use a minus sign (`-`) before a field name to sort in descending order, or a plus sign (`+`) or no sign for ascending order. +For example: + +"http://localhost:3000/collections?sortby=-created" + +"http://localhost:3000/collections?sortby=title" + +### Paging (Page-wise Results) +Retrieve large result lists page by page. The links in the response help you to navigate. + +"http://localhost:3000/collections?limit=10&token=0" + +"http://localhost:3000/collections?limit=10&token=10" + +--- + ## CQL2 Filter Examples CQL2 is a powerful language for complex filters. The API supports both CQL2-Text and CQL2-JSON. @@ -100,29 +126,6 @@ CQL2-JSON is machine-readable and especially suitable for complex, nested filter "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" ---- - -## Common Search Patterns - -Here you will find typical use cases for search, pagination, and sorting. - -### Paging (Page-wise Results) -Retrieve large result lists page by page. The links in the response help you to navigate. - -"http://localhost:3000/collections?limit=10&token=0" - -"http://localhost:3000/collections?limit=10&token=10" - - -### Sorting -Sort by different fields, e.g., by creation date or title. - -"http://localhost:3000/collections?sortby=-created" - -"http://localhost:3000/collections?sortby=title" - ---- - ## Advanced Examples - CQL2-JSON: Combined spatial and temporal filter From b347842377e701200568ecdb813597bb0a894f23 Mon Sep 17 00:00:00 2001 From: jklaer Date: Sun, 25 Jan 2026 12:34:22 +0100 Subject: [PATCH 5/7] Update API examples documentation to enhance clarity on queryables, sorting, and paging --- api/docs/api-examples.md | 45 +++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index 1f9e183..d6c8b14 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -61,9 +61,11 @@ For example: "http://localhost:3000/collections/vegetation" ### Queryables -Shows which fields can be used for filtering and sorting. +Lists all available fields (properties) that can be used for filtering and sorting in collection searches. +The response includes each field’s name, data type, and—where applicable—possible values or value ranges. +Use this endpoint to discover which attributes you can use in your queries and how to reference them in filter expressions. -"http://localhost:3000/queryables" +"http://localhost:3000/collections-queryables" --- @@ -74,14 +76,22 @@ Here you will find typical use cases for sorting and pagination. ### Sorting Sort by different fields, e.g., by creation date or title. Use a minus sign (`-`) before a field name to sort in descending order, or a plus sign (`+`) or no sign for ascending order. + For example: "http://localhost:3000/collections?sortby=-created" "http://localhost:3000/collections?sortby=title" + ### Paging (Page-wise Results) -Retrieve large result lists page by page. The links in the response help you to navigate. +Retrieve large result lists page by page. +The `token` parameter in this API is a simple offset: it tells the server how many collections to skip before starting to return results. +For example, `token=0` means start at the beginning, `token=10` means skip the first 10 collections and return the next ones. +It is not a page number, and it is not related to a specific collection ID. +Always use the value provided by the API for consistent paging, especially if the API ever changes its paging logic. + +For example: "http://localhost:3000/collections?limit=10&token=0" @@ -91,10 +101,17 @@ Retrieve large result lists page by page. The links in the response help you to ## CQL2 Filter Examples -CQL2 is a powerful language for complex filters. The API supports both CQL2-Text and CQL2-JSON. +CQL2 is a powerful language for complex filters. +The API supports both CQL2-Text and CQL2-JSON. + +To use CQL2 filtering, provide your filter expression in the `filter` parameter. +The `filter-lang` parameter specifies the format: use `cql2-text` for human-readable filters (default), or `cql2-json` for machine-readable JSON filters. + +For a complete list of all supported CQL2 operators and filter options in this API, see: +- [CQL2 Filtering Documentation](cql2-filtering.md) ### CQL2-Text -CQL2-Text is human-readable and suitable for simple to medium filters. +CQL2-Text is a human-readable format for filter expressions. - License filter: "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" @@ -118,6 +135,10 @@ CQL2-Text is human-readable and suitable for simple to medium filters. ### CQL2-JSON CQL2-JSON is machine-readable and especially suitable for complex, nested filters and geo-objects. + +**Note:** All filters shown here can also be expressed using CQL2-Text. +However, for complex or deeply nested filters (especially with geo-objects), CQL2-JSON is often easier to write and more commonly used. + - Bounding Box (S_INTERSECTS): "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" @@ -136,21 +157,11 @@ CQL2-JSON is machine-readable and especially suitable for complex, nested filter "http://localhost:3000/collections?q=M%C3%BCnster" -- Show only certain fields: +- Limit the number of results: "http://localhost:3000/collections?limit=1" ---- - -## Check Queryables Details - -The Queryables endpoint shows which fields you can use for filtering and sorting: - -"http://localhost:3000/queryables" - ---- - -### Example of a successful collection search +## Example of a successful collection search "http://localhost:3000/collections?limit=1&q=sentinel" From 9883c44d99beeca4c74f08d01943e26a93af94ab Mon Sep 17 00:00:00 2001 From: jklaer Date: Sun, 25 Jan 2026 15:38:17 +0100 Subject: [PATCH 6/7] Enhance API examples documentation with additional details on URL encoding and limit parameter usage --- api/docs/api-examples.md | 50 ++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index d6c8b14..f5301f1 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -1,3 +1,16 @@ +# Disclaimer on Special Characters + +When using filter parameters or search queries, special characters (such as spaces, umlauts, or symbols) must be properly URL-encoded. +Most browsers and tools like curl handle this automatically. +However, if you write URLs by hand, make sure to encode special characters: +- Space → `%20` (e.g., `Sentinel-2 L2A` → `Sentinel-2%20L2A`) +- Umlaut (ü) → `%C3%BC` (e.g., `Münster` → `M%C3%BCnster`) + +For a complete list of URL-encoded special characters, see: +https://www.w3schools.com/tags/ref_urlencode.asp + +All examples in this documentation use clear, human-readable text for better readability. +When copying URLs into a browser or terminal, ensure special characters are encoded as needed. # STAC Atlas API – Example Requests & Search Patterns @@ -49,6 +62,11 @@ Returns a list of all collections. "http://localhost:3000/collections" +### Limit the number of results +Returns only the specified number of collections (e.g., 1 result): + +"http://localhost:3000/collections?limit=1" + ### Collections (with parameters) Returns a list of collections. You can filter the search with parameters. @@ -112,25 +130,27 @@ For a complete list of all supported CQL2 operators and filter options in this A ### CQL2-Text CQL2-Text is a human-readable format for filter expressions. + - License filter: - "http://localhost:3000/collections?filter=license%20%3D%20'MIT'" - + "http://localhost:3000/collections?filter=license='MIT'" + - Title exactly "Sentinel-2 L2A": - "http://localhost:3000/collections?filter=title%20%3D%20'Sentinel-2%20L2A'" + "http://localhost:3000/collections?filter=title='Sentinel-2 L2A'" - Title is one of several: - "http://localhost:3000/collections?filter=title%20IN%20('Sentinel-2%20L2A','CHELSA%20Climatologies')" + "http://localhost:3000/collections?filter=title IN ('Sentinel-2 L2A','CHELSA Climatologies')" - Combined filters: - "http://localhost:3000/collections?filter=license%20%3D%20'MIT'%20AND%20id%20%3E%2010" + "http://localhost:3000/collections?filter=license='MIT' AND id>10" - Multiple licenses (OR): - "http://localhost:3000/collections?filter=license%20%3D%20'CC-BY-4.0'%20OR%20license%20%3D%20'MIT'" + "http://localhost:3000/collections?filter=license='CC-BY-4.0' OR license='MIT'" + ### CQL2-JSON @@ -141,25 +161,15 @@ However, for complex or deeply nested filters (especially with geo-objects), CQL - Bounding Box (S_INTERSECTS): - "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D" + "http://localhost:3000/collections?filter-lang=cql2-json&filter={"op":"s_intersects","args":[{"property":"spatial_extend"},{"type":"Polygon","coordinates":[[[7,51],[8,51],[8,52],[7,52],[7,51]]]}]}" - Time interval (T_INTERSECTS): - "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D" - -## Advanced Examples - -- CQL2-JSON: Combined spatial and temporal filter - - "http://localhost:3000/collections?filter-lang=cql2-json&filter=%7B%22op%22%3A%22and%22%2C%22args%22%3A%5B%7B%22op%22%3A%22s_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22spatial_extend%22%7D%2C%7B%22type%22%3A%22Polygon%22%2C%22coordinates%22%3A%5B%5B%5B7%2C51%5D%2C%5B8%2C51%5D%2C%5B8%2C52%5D%2C%5B7%2C52%5D%2C%5B7%2C51%5D%5D%5D%7D%5D%7D%2C%7B%22op%22%3A%22t_intersects%22%2C%22args%22%3A%5B%7B%22property%22%3A%22datetime%22%7D%2C%7B%22interval%22%3A%5B%222020-01-01%22%2C%222025-12-31%22%5D%7D%5D%7D%5D%7D" - -- Free text search with special characters (Münster): - - "http://localhost:3000/collections?q=M%C3%BCnster" + "http://localhost:3000/collections?filter-lang=cql2-json&filter={"op":"t_intersects","args":[{"property":"datetime"},{"interval":["2020-01-01","2025-12-31"]}]}" -- Limit the number of results: +- Combined spatial and temporal filter: - "http://localhost:3000/collections?limit=1" + "http://localhost:3000/collections?filter-lang=cql2-json&filter={"op":"and","args":[{"op":"s_intersects","args":[{"property":"spatial_extend"},{"type":"Polygon","coordinates":[[[7,51],[8,51],[8,52],[7,52],[7,51]]]}]},{"op":"t_intersects","args":[{"property":"datetime"},{"interval":["2020-01-01","2025-12-31"]}]}]}" ## Example of a successful collection search From 9117a0995336ff72dc42f57baf9982bd2af9810a Mon Sep 17 00:00:00 2001 From: jklaer Date: Sun, 25 Jan 2026 16:04:09 +0100 Subject: [PATCH 7/7] Deleted an unnecessary line. --- api/docs/api-examples.md | 1 - 1 file changed, 1 deletion(-) diff --git a/api/docs/api-examples.md b/api/docs/api-examples.md index f5301f1..a223767 100644 --- a/api/docs/api-examples.md +++ b/api/docs/api-examples.md @@ -75,7 +75,6 @@ Returns a list of collections. You can filter the search with parameters. ### Single Collection To retrieve the metadata of a specific collection, use the endpoint `/collections/{id}` where `{id}` is the STAC ID string of the desired collection. Replace `{id}` with the actual collection identifier (e.g., `vegetation`). -For example: "http://localhost:3000/collections/vegetation" ### Queryables