up demo

SEARCH_ENDPOINT.md

@@ -0,0 +1,201 @@
+# OpenEventDatabase Search Endpoint Documentation
+
+This document describes the `/event/search` endpoint of the OpenEventDatabase API, which allows you to search for events using a GeoJSON geometry.
+
+## Overview
+
+The search endpoint provides a way to search for events using a GeoJSON geometry in the request body. This is particularly useful when you need to search for events within a complex shape that cannot be easily expressed using query parameters like `bbox` or `near`.
+
+## Endpoint
+
+```
+POST /event/search
+```
+
+## Request Format
+
+The request body should be a JSON object containing a `geometry` field with a valid GeoJSON geometry. The geometry can be any valid GeoJSON geometry type (Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection).
+
+Example request body:
+
+```json
+{
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+      [
+        [2.3, 48.8],
+        [2.4, 48.8],
+        [2.4, 48.9],
+        [2.3, 48.9],
+        [2.3, 48.8]
+      ]
+    ]
+  }
+}
+```
+
+## Query Parameters
+
+The search endpoint supports all the same query parameters as the `/event` endpoint. These parameters can be used to further refine your search beyond the geometric constraints.
+
+For detailed information about the available query parameters, see the [API Query Parameters Documentation](API_QUERY_PARAMS.md).
+
+### Additional Parameters
+
+In addition to the parameters documented in the API Query Parameters Documentation, the search endpoint also supports the following parameters:
+
+#### `where:osm`
+
+Filters events by OpenStreetMap ID.
+
+- **Format**: String
+- **Example**: `where:osm=R12345`
+- **Description**: Returns events associated with the specified OpenStreetMap ID.
+
+#### `where:wikidata`
+
+Filters events by Wikidata ID.
+
+- **Format**: String
+- **Example**: `where:wikidata=Q90`
+- **Description**: Returns events associated with the specified Wikidata ID.
+
+## Response Format
+
+The response format is the same as for the `/event` endpoint. It returns a GeoJSON FeatureCollection containing the events that match the query parameters and intersect with the provided geometry.
+
+Example response:
+
+```json
+{
+  "type": "FeatureCollection",
+  "features": [
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [2.35, 48.85]
+      },
+      "properties": {
+        "id": "123e4567-e89b-12d3-a456-426614174000",
+        "label": "Conference event in Paris",
+        "what": "event.conference",
+        "where": "Paris",
+        "start": "2025-09-10T23:00:00",
+        "stop": "2026-05-10T23:00:00",
+        "createdate": "2025-09-15T23:00:00",
+        "lastupdate": "2025-09-15T23:00:00"
+      }
+    }
+  ],
+  "count": 1
+}
+```
+
+## Examples
+
+### Search for events within a polygon
+
+```
+POST /event/search
+Content-Type: application/json
+
+{
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+      [
+        [2.3, 48.8],
+        [2.4, 48.8],
+        [2.4, 48.9],
+        [2.3, 48.9],
+        [2.3, 48.8]
+      ]
+    ]
+  }
+}
+```
+
+Returns events located within the specified polygon.
+
+### Search for events within a polygon with additional filters
+
+```
+POST /event/search?what=sport.match&when=today
+Content-Type: application/json
+
+{
+  "geometry": {
+    "type": "Polygon",
+    "coordinates": [
+      [
+        [2.3, 48.8],
+        [2.4, 48.8],
+        [2.4, 48.9],
+        [2.3, 48.9],
+        [2.3, 48.8]
+      ]
+    ]
+  }
+}
+```
+
+Returns sports matches taking place today within the specified polygon.
+
+### Search for events near a point with a buffer
+
+```
+POST /event/search?buffer=5000
+Content-Type: application/json
+
+{
+  "geometry": {
+    "type": "Point",
+    "coordinates": [2.3522, 48.8566]
+  }
+}
+```
+
+Returns events within 5km of the specified point (Paris).
+
+## Caching and Rate Limiting
+
+The OpenEventDatabase API implements caching and rate limiting to improve performance and prevent abuse.
+
+### Caching
+
+- POST requests to `/event/search` are not cached.
+- The results of GET requests to `/event` are cached for 60 seconds.
+- If you need fresh data, you can bypass the cache by adding a unique query parameter (e.g., `?_=timestamp`).
+
+### Rate Limiting
+
+- POST requests to `/event/search` are limited to 20 requests per minute per IP address.
+- If you exceed this limit, you will receive a `429 Too Many Requests` response with a `Retry-After` header indicating when you can try again.
+
+For more information about the anti-spam and caching measures implemented in the API, see the [Anti-Spam and Caching Measures Documentation](ANTI_SPAM_MEASURES.md).
+
+## Error Handling
+
+The search endpoint may return the following error responses:
+
+- `400 Bad Request`: If the request body is not valid JSON or does not contain a `geometry` field.
+- `429 Too Many Requests`: If you have exceeded the rate limit.
+- `500 Internal Server Error`: If there is an error processing the request.
+
+Error responses include a JSON object with an `error` field containing a description of the error.
+
+Example error response:
+
+```json
+{
+  "error": "Request body must contain a 'geometry' field"
+}
+```
+
+## Limitations
+
+- Only the first 200 events are returned by default. Use the `limit` parameter to adjust this.
+- Complex geometries may result in slower query performance.
+- The API may return a 500 Internal Server Error if there are issues with the database connection or if the query is malformed.