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:

{
  "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.

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:

{
  "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.

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:

{
  "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.