oedb-backend/doc/SEARCH_ENDPOINT.md

# 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.