Mardi Gras FYI for developers
A free, read-only API and MCP server for New Orleans (Orleans Parish) Carnival parade schedules, routes, krewes and local advice. No key needed.
Dates and times are local to New Orleans (America/Chicago). A parade’s time is when it departs the start of its route; it reaches any other block later. Follow live progress on Routewise. Every parade includes a citation link to its mardigras.fyi page. Please credit “Mardi Gras FYI” with a link when you show this data.
REST API
Base URL https://mardigras.fyi/api/v1. The OpenAPI 3.1 document (https://mardigras.fyi/api/openapi.json) describes every parameter and schema.
| Request | Returns |
|---|---|
GET /parades?year=2027&date=2027-02-05 | Parades by year, date, start_date/end_date, period, area or q (name) |
GET /parades/{event_id} | One parade with its profile |
GET /parades/{event_id}/route | Route as a GeoJSON Feature |
GET /parades/nearby?lat=29.9266&lon=-90.102&within_hours=2 | Parades near a point by departure window |
GET /streets/parades?street=Napoleon&cross_street=St.%20Charles | Parades on a street or through a corner |
GET /krewes, /krewes/{name} | Krewes and krewe details |
GET /seasons/2027 | Carnival start, parade weekends and Mardi Gras day |
GET /guide?query=bathrooms | Local advice articles |
GET /score?street=Napoleon&cross_street=St.%20Charles&dates=2027-02-06 | Carnival Score for a corner, address or lat/lon, for the season or chosen nights |
GET /score/compare?at=29.93,-90.10&at=Canal%20%26%20Carrollton | Compare two to six places |
GET /score/grid | The scored hex grid for the season and each parade day (JSON) |
curl
curl "https://mardigras.fyi/api/v1/streets/parades?year=2027&street=Napoleon&cross_street=St.%20Charles"
JavaScript
const response = await fetch("https://mardigras.fyi/api/v1/parades?year=2027&period=second_weekend");
const {data, meta} = await response.json();
for (const parade of data) console.log(parade.date, parade.timeLabel, parade.name, parade.citation.url);
Python
import requests
r = requests.get("https://mardigras.fyi/api/v1/parades/nearby",
params={"lat": 29.9266, "lon": -90.102, "from": "2027-02-05T17:00", "within_hours": 2})
r.raise_for_status()
for parade in r.json()["data"]["departingInWindow"]:
print(parade["name"], "departs in", parade["minutesUntilDeparture"], "minutes")
Responses
Successful responses are {"data": …, "meta": {"apiVersion": "1", "attribution": …, "timezone": "America/Chicago", "generatedAt": …}}. Each parade carries citation and provenance; provenance is null until source verification details are published for that record. Parades without a route map are listed under unmapped in street and nearby results: whether they pass is unknown, not “no”.
Location privacy
/parades/nearby takes coordinates because your application supplies them for its own users. They are used only to answer that request: Mardi Gras FYI does not store or log them, and responses are not tied to a user. Requests pass through Cloudflare, which hosts the service. The MCP server never asks for coordinates. Its nearby tool takes a street corner instead.
Errors
Errors use one shape, {"error": {"code", "message", "details"?, "docs"}}, and are never cached.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_parameter | A parameter is missing or malformed; details lists each one |
| 404 | not_found | Unknown parade, krewe, path, or streets that do not meet |
| 404 | street_not_found | No New Orleans street matches; details.suggestions may help |
| 409 | ambiguous_intersection | The names meet at more than one corner; details.candidates lists each with full street names |
| 405 | method_not_allowed | The API is read-only |
| 429 | rate_limited | Too many requests; wait Retry-After seconds |
| 503 | service_unavailable | Temporary failure; retry shortly |
Rate limits, caching and CORS
Each client address may make 120 requests per 60 seconds. Over the limit you receive 429 with a Retry-After header. Data responses are cacheable for five minutes (one minute for “now” queries). All responses allow cross-origin requests from any site.
Calendar feeds
Subscribable iCalendar feeds, refreshed every six hours by most clients: /calendar/2027.ics (the season), /calendar/2027/{first-weekend|second-weekend|mardi-gras-day}.ics, and /calendar/parade/{event_id}.ics. UIDs match the /api/calendar downloads, so updates replace events rather than duplicating them. Untimed parades are date-only. Times are New Orleans departures.
To show upcoming parades or one parade on your own site, use the embeddable widget.
MCP server
Streamable HTTP endpoint: https://mardigras.fyi/mcp. Read-only, no sign-in, no user data. Connect it to an assistant so its answers come from this calendar.
Claude
In Claude, open Settings → Connectors, choose Add custom connector and enter https://mardigras.fyi/mcp. In Claude Code:
claude mcp add --transport http mardi-gras https://mardigras.fyi/mcp
ChatGPT
Turn on developer mode in ChatGPT settings (under Apps → Advanced settings), then create an app with the MCP server URL https://mardigras.fyi/mcp and no authentication. Availability depends on your ChatGPT plan.
Cursor
Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"mardi-gras": { "url": "https://mardigras.fyi/mcp" }
}
}
Tools
| Tool | Use |
|---|---|
find_events | Parades by year, single date, date range, weekend, area or name |
get_event | One parade by event_id |
find_parades_on_street | Parades running along a street, or passing a corner with cross_street |
find_parades_near_intersection | Parades near a corner that depart within a time window |
get_krewe | Krewe profile, traditions, permit figures and parades by year |
get_parade_route | Route GeoJSON and route points for walking links |
search_carnival_guide | Local advice: kids, arrival, restrooms, rideshares, crossing, throws, weather, trackers |
export_calendar | iCalendar file for selected parades |
get_walking_directions | Google Maps walking link to a point on the route |
get_carnival_score | Carnival Score for an address, corner or coordinates, optionally for chosen nights |
compare_locations | Two to six places to stay compared side by side |
Questions or corrections: contact us.