Docs / Event Data API
Event Data API
Concerts, theatre, exhibitions and cinema with geocoded venues and UTC instants for every time. Where the source publishes per-showing ticket inventory it is recorded at every scrape, so successive scrapes give you sell-through rather than a snapshot.
Live
https://api.softon.dev/v1
v1 · stable
Endpoints
| Endpoint | Route | Returns |
|---|---|---|
| List events | GET /v1/events |
collection |
| Retrieve an event | GET /v1/events/{id} |
single object |
| Retrieve a venue | GET /v1/venues/{id} |
single object |
The Event object
The fields below appear on the dataset's primary resource. Endpoint pages list any fields specific to them.
| Field | Type | Description |
|---|---|---|
id |
string | Stable identifier, "<source>:<source id>". |
source |
string | Which scraper produced this event. |
slug |
string · nullable | The source's own readable identifier for the event — what to build a stable, human-readable URL from, rather than the opaque `id`. NOT unique and not an identifier: one source derives it from a film title and a cinema name, so the same film at two cinemas shares a slug. Null where the source publishes none, and a value that stops arriving is kept rather than nulled, because a stale slug is a working link and an empty one is a 404. |
name |
string | Event name as published. |
category |
string · nullable | The source's own category slug, not normalised and not a closed set — it follows the upstream, so it also contains venue and festival names (`hayal-kahvesi`, `gabalafest`). `cinema`, `concerts` and `theatre` are three quarters of the corpus between them; `kids`, `sport`, `seminar`, `master-class`, `circus`, `other` and `exhibitions` make up most of the rest. Do not build a fixed facet from this list — read the values you actually receive. |
venue |
object · nullable | id, name, address, lat, lng. Coordinates where the source geocodes. |
starts_at |
timestamp · nullable | Start time as an RFC 3339 instant in UTC. Convert with the venue's timezone for display — all current venues are Asia/Baku (UTC+4). |
ends_at |
timestamp · nullable | End time in UTC, when the source publishes one. |
price |
object · nullable | min, max and currency across ticket tiers. |
age_limit |
string · nullable | Age restriction as published, e.g. "16+". |
tickets_available |
integer · nullable | Live inventory. null where the source does not expose it — never 0 as a stand-in. |
description |
string · nullable | Editorial copy for the event. |
url |
string · nullable | Canonical page on the source site. |
external_url |
string · nullable | Information or ticketing page. NOT guaranteed to be a purchase link — cinema sources have no dereferenceable buy href. |
poster_url |
string · nullable | Artwork, highest resolution the source offers. |
ingested_at |
timestamp | When this version was stored. |