Event Search

Note: This documentation covers Event Search specific features. For common concepts like response format, pagination, and general query parameters, see the Getting Started Guide.

Overview

The Events search endpoint provides a search interface for querying events.

It supports the following types of filtering:

• Text search: Full-text search on event names, descriptions, and associated pinpoint details
• Collection filtering: Filter by lists, livemaps, pinpoints, portals, or users
• Date filtering: Filter by event dates or update timestamps
• Tag filtering: Filter by tags with support for AND/OR logic
• Geographic filtering: Filter by bounding box coordinates and altitude ranges

Endpoint: GET /v3.0/events/search

Response Format

When search is successful, the endpoint automatically enriches each event result with complete pinpoint informations. This means you'll receive full pinpoint details (name, address, coordinates, etc.) for each event in the response, without needing to make additional API calls.

Response Structure:

{
"count": 338,
"next": "https://api.getwemap.com/v3.0/events/search?limit=20&offset=20&query=event+name",
"previous": null,
"results": [
    {
        "created": "2022-07-05T11:50:51.564228Z",
        "dates": [
            {
                "start": "2022-06-28T14:00:00+02:00",
                "end": "2022-06-28T18:00:00+02:00"
            },
            {
                "start": "2022-07-08T16:15:00+02:00",
                "end": "2022-07-08T17:00:00+02:00"
            },
        ],
        "dates_have_times": true,
        "dates_label": null,
        "description": "Event description",
        "external_data": null,
        "id": 1234567890,
        "link_url": null,
        "media_credits": "",
        "media_type": "image",
        "media_url": "https://api.getwemap.com/images/pps-events/d0c85cf10aff58450dfede39.00747722.jpg",
        "name": "Event name",
        "pinpoint": {
            "address": "Some address",
            "altitude": null,
         // other pinpoint fields...
        },
        "tags": [
            "some-tag",
            "another-tag",
        ],
        "translation_group": null,
        "user_lang": "fr",
        "updated": "2023-12-05T11:50:51.564246Z"
    },
    // ... more events
  ]
}

Note: For general response format details (count, next, previous, results fields), see the Getting Started Guide.

Error Responses

400 Bad Request

Returned when:

• No search criteria are provided (at least one criterion is required, except sort_by_name)
• Invalid date format
• Invalid bounding box parameters
• Invalid tag format

Permissions

The endpoint respects event visibility permissions:

• Public events: Visible to everyone
• Shared events: Visible if the livemap parameter is provided and if events belong to that livemap
• Private events: Only visible to the event owner (authenticated users can see their own events)

The permissions are automatically applied based on the authenticated user and on the livemap parameter if provided.

Query Parameters

Text Search

query (string, optional)

Full-text search on the event's name, description, and associated pinpoint details (address, description, name).

Example:

GET /v3.0/events/search?query=music festival

Searched Fields:

• Event description
• Event name
• Pinpoint address
• Pinpoint description
• Pinpoint name

query_mode (string, optional)

Controls how the query is interpreted:

• regular (default): Standard search with AND operator between terms
• phrase: Phrase matching mode for exact phrase searches

Examples:

Regular mode (default):

GET /v3.0/events/search?query=rock concert
GET /v3.0/events/search?query=rock concert&query_mode=regular

This will find events that contain both "rock" AND "concert" anywhere in the searched fields (e.g., "rock music concert", "concert featuring rock bands").

Phrase mode:

GET /v3.0/events/search?query=rock concert&query_mode=phrase

This will find events that contain the exact phrase "rock concert" (e.g., "rock concert in Paris", but not "rock music concert").

Filtering by Collection

These parameters allow you to filter events by the collections or objects they are linked to : lists, livemaps, pinpoints, portals, users. All of them are specified by their ID.

list (integer, optional)

Filter events belonging to a specific list.

Example:

GET /v3.0/events/search?list=123

livemap (integer, optional)

Filter events from all lists that belong to a specific livemap.

Example:

GET /v3.0/events/search?livemap=456

pinpoint (integer, optional)

Filter events that are linked to a specific pinpoint.

Example:

GET /v3.0/events/search?pinpoint=789

portal (integer, optional)

Filter events for a specific portal (searches all lists within livemaps belonging to that portal).

Example:

GET /v3.0/events/search?portal=10

user (integer, optional)

Filter events created by a specific user.

Example:

GET /v3.0/events/search?user=42

Date Filtering

You can filter events based on their dates and update timestamps. All date parameters accept ISO 8601 date and datetime formats.

Valid formats:

• Date only: 2024-01-01 (time defaults to 00:00:00)
• Full datetime with UTC: 2024-01-01T00:00:00Z or 2024-01-01T00:00:00.000Z

start_date (ISO 8601 datetime, optional)

Filter events that end on or after this date.

Examples:

GET /v3.0/events/search?start_date=2024-01-01
GET /v3.0/events/search?start_date=2024-01-01T00:00:00Z
GET /v3.0/events/search?start_date=2024-01-01T00:00:00.000Z

end_date (ISO 8601 datetime, optional)

Filter events that start on or before this date.

Examples:

GET /v3.0/events/search?end_date=2024-12-31
GET /v3.0/events/search?end_date=2024-12-31T23:59:59Z
GET /v3.0/events/search?end_date=2024-12-31T23:59:59.000Z

updated__gte (ISO 8601 datetime, optional)

Filter events updated on or after this date.

Examples:

GET /v3.0/events/search?updated__gte=2024-06-01
GET /v3.0/events/search?updated__gte=2024-06-01T00:00:00Z
GET /v3.0/events/search?updated__gte=2024-06-01T15:54:00.000Z

Tag Filtering

tags (comma-separated string, optional)

Filter events that have the specified tags.

Use commas (,) to separate tag groups, which creates AND logic between groups. Within a tag group, use the pipe character (|) to create OR logic between tags.

Format:

• Simple tags: tag1,tag2,tag3
• Tag groups with OR: tag1|tag2,tag3 (means: (tag1 OR tag2) AND tag3)

Example:

GET /v3.0/events/search?tags=music,outdoor
GET /v3.0/events/search?tags=rock|pop,jazz

tags__overlap (comma-separated string, optional)

Filter events that have at least one of the specified tags. Note: | is not allowed in this parameter.

Example:

GET /v3.0/events/search?tags__overlap=music,sports,art

Geographic Filtering

You can filter events based on the geographic location of the pinpoint they belong to. These filters use bounding box coordinates and altitude ranges.

center_latitude (float, optional)

Latitude of the bounding box center. Must be used together with center_longitude, latitude_delta, and longitude_delta.

Example:

GET /v3.0/events/search?center_latitude=48.8566&center_longitude=2.3522&latitude_delta=0.1&longitude_delta=0.1

center_longitude (float, optional)

Longitude of the bounding box center. Must be used together with center_latitude, latitude_delta, and longitude_delta.

latitude_delta (float, optional)

Height of the bounding box in degrees. Must be positive and ≤ 90. Required when using bounding box filtering.

longitude_delta (float, optional)

Width of the bounding box in degrees. Must be positive and ≤ 180. Required when using bounding box filtering.

Note: All four parameters (center_latitude, center_longitude, latitude_delta, longitude_delta) must be provided together to enable bounding box filtering.

minaltitude (float, optional)

Minimum altitude in meters (inclusive). Must be used together with maxaltitude.

Example:

GET /v3.0/events/search?minaltitude=0&maxaltitude=1000

maxaltitude (float, optional)

Maximum altitude in meters (exclusive). Must be used together with minaltitude.

Sorting

You can sort the results by relevance score (default sorting) or by event name.

relevance sorting (default sorting)

Results are ranked by relevance, which considers:

• Recency: More recent events (especially within the last 28 days) are ranked higher
• Search priority: Events inherit the search_priority value from their associated pinpoint (location). This is an integer field on the pinpoint that can be set to a value between 1 and 100 (or null). Events with higher priority values appear first in search results.
• Text match quality: Better matches to your search query are ranked higher

sort_by_name (string, optional)

Sort results by event name. Values:

• asc: Ascending order
• desc: Descending order

Example:

GET /v3.0/events/search?sort_by_name=asc

Pagination

For pagination parameters (limit and offset), see the Getting Started Guide.