Byma APIbyma.com.br ↗
Access public event listings from Byma's Brazilian ticketing platform. Filter by city, date range, and keyword. Returns venue, coordinates, and event URLs.
What is the Byma API?
The Byma.com.br API exposes one endpoint — list_events — that returns paginated public events from Brazil's Byma ticketing platform, with up to 10 fields per event including title, venue, address, coordinates, start date, start time, and a direct event page URL. You can filter results by city name, free-text search against event titles, and ISO date range bounds, all expressed in Brazil time (America/Sao_Paulo).
curl -X GET 'https://api.parse.bot/scraper/ecba50f2-8fcb-4a11-a4e2-a38453b5eb8d/list_events?city=curitiba&from_date=2026-09-01' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace byma-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Byma Events API — browse upcoming events with city and date filters."""
from parse_apis.byma_com_br_api import Byma, InputFormatInvalid
client = Byma()
# List upcoming events in Campinas, capped at 5 total items.
for event in client.events.list(city="campinas", limit=5):
print(event.title, "|", event.venue, "|", event.start_date, event.start_time)
# Drill into the first event matching a search term.
hit = client.events.list(search="samba", limit=1).first()
if hit is not None:
print(hit.title)
print(f" Where: {hit.venue} — {hit.address}")
print(f" When: {hit.start_date} {hit.start_time}")
print(f" Link: {hit.url}")
if hit.latitude is not None:
print(f" Coords: {hit.latitude}, {hit.longitude}")
# Date-range filter with error handling for invalid dates.
try:
for event in client.events.list(from_date="2026-10-01", to_date="2026-10-31", limit=3):
print(event.title, event.start_date)
except InputFormatInvalid:
print("Invalid date range provided.")
print("exercised: events.list (city / search / date-range filters)")
Returns one page of events from Byma's public 'Explorar eventos' catalogue, ordered by start date ascending. Each row is one event with title, venue, address, coordinates, start_date (YYYY-MM-DD) and start_time (HH:MM) expressed in Brazil time (America/Sao_Paulo), the event page url and cover image. The site only publishes a single start moment per event, so end_date and end_time are always null. When from_date is omitted the listing starts at today (the site's default 'upcoming' view); pass an earlier from_date to include past events. Pagination is page (1-based, default 1) and per_page (default 12, capped at 100); total is the number of events matching the site-side filters (search and dates), matched_total additionally reflects the local city filter, and has_more says whether a further page exists. Without city, one upstream request is made per call. With city, the whole date-filtered catalogue is fetched (a few hundred events, one or two upstream requests) and filtered locally on the address text, accent- and case-insensitively, before paging; a city with no events yields an empty events array and matched_total 0. search is the site's own search box and matches event titles only, not addresses. Invalid dates are rejected with a stale_input error.
| Param | Type | Description |
|---|---|---|
| city | string | City name to match within the event address (e.g. curitiba). Case- and accent-insensitive substring match applied locally after fetching the catalogue. Omitted = all cities. |
| page | integer | 1-based page number over the (filtered) result stream. |
| search | string | Free-text search forwarded to the site's search box; matches event titles only. Omitted = no text filter. |
| to_date | string | ISO date YYYY-MM-DD (Brazil time). Only events starting on or before this day are returned. Omitted = no upper bound. |
| per_page | integer | Events per page; values above 100 are clamped to 100. |
| from_date | string | ISO date YYYY-MM-DD (Brazil time). Only events starting on or after this day are returned. Omitted = today. |
{
"type": "object",
"fields": {
"page": "integer, the page returned",
"total": "integer, events matching the site-side filters (search/date range) regardless of city",
"events": "array of event objects: id (Byma event id), title, venue, address, latitude, longitude (may be null), start_date YYYY-MM-DD, start_time HH:MM (America/Sao_Paulo), end_date and end_time (always null, not published by the site), url (event page), image_url (cover image)",
"has_more": "boolean, whether a further page of matched events exists",
"per_page": "integer, effective page size after clamping",
"matched_total": "integer, events matching all filters including city (equals total when city is omitted)"
},
"sample": {
"data": {
"page": 1,
"total": 192,
"events": [
{
"id": "6a50d0d913473100042dfd25",
"url": "https://byma.com.br/event/6a50d0d913473100042dfd25",
"title": "AIMEC Show Case - 08",
"venue": "Iff! Eventos",
"address": "Av. José de Sousa Campos, 425 - Nova Campinas, Campinas - SP, 13035-220, Brasil",
"end_date": null,
"end_time": null,
"latitude": -22.9028429,
"image_url": "https://res.cloudinary.com/htkavmx5a/image/upload/v1783681123/syv4x7wag8m4k5iptacq.jpg",
"longitude": -47.0480578,
"start_date": "2026-09-20",
"start_time": "16:00"
}
],
"has_more": true,
"per_page": 3,
"matched_total": 38
},
"status": "success"
}
}About the Byma API
What the API returns
The list_events endpoint returns a page of events from Byma's public catalogue, ordered by start date ascending. Each event object includes a Byma event id, title, venue name, address, latitude and longitude (coordinates may be null for some events), start_date in YYYY-MM-DD format, start_time in HH:MM format, and the full event page url on byma.com.br. All dates and times are in Brazil time (America/Sao_Paulo).
Filtering and pagination
The city parameter does a case- and accent-insensitive substring match against the event address field — passing curitiba will match events in Curitiba regardless of accents or capitalisation. The search parameter filters by event title text. from_date and to_date accept ISO dates and constrain the event start date; from_date defaults to today when omitted. The per_page parameter controls page size up to a maximum of 100 (values above 100 are clamped). Use the page parameter for 1-based pagination.
Response envelope
Beyond the events array, each response includes total (events matching site-level filters, i.e. search and date range, before city filtering), matched_total (events matching all filters including city), page, per_page (effective after clamping), and has_more (boolean indicating whether additional pages exist). The distinction between total and matched_total lets you assess how many events exist in a date/search window versus how many fall in a specific city.
The Byma API is a managed, monitored endpoint for byma.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when byma.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official byma.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a city-specific event calendar for Curitiba, São Paulo, or any Brazilian city using the
cityfilter andstart_datefields. - Aggregate upcoming Byma events within a date window using
from_dateandto_dateto feed a weekly event digest newsletter. - Plot event density on a map using the
latitudeandlongitudefields returned per event. - Monitor when new events are added to the Byma catalogue by comparing
totalcounts across daily polling runs. - Search for specific artists or event names using the
searchparameter and retrieve direct event page URLs for deep-linking. - Track venue activity over time by filtering events by
venuename extracted from results and grouping bystart_date.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Byma have an official developer API?+
What does the `total` field represent, and how is it different from `matched_total`?+
total counts all events that match the site-level filters — search and the date range (from_date/to_date) — regardless of the city parameter. matched_total is the count after also applying the city substring filter. When city is omitted, the two values are equal.Are coordinates always present in event results?+
latitude and longitude fields may be null for events where the venue location was not resolved to coordinates on the source platform. Other location fields — venue, address — are still returned when coordinates are absent.Does the API return ticket pricing or purchase links?+
url on byma.com.br, but ticket prices, availability counts, and checkout URLs are not included in the response. You can fork this API on Parse and revise it to add an endpoint that fetches per-event detail pages where pricing information may appear.Is event coverage limited to specific Brazilian cities or states?+
city parameter does a substring match against the address field, so you can approximate region filtering by passing a city name. Events outside Brazil are not known to appear in the catalogue.