{"openapi":"3.0.0","paths":{"/api/v1/events/search":{"get":{"operationId":"searchPublicEvents","summary":"Search upcoming public events by location","description":"Returns upcoming public events near a given location, sorted by distance then start date. Supply lat+lng for coordinate-based search, or any combination of zip, city, state, and country — at least one location parameter is required. If both coordinates and address fields are supplied, coordinates take precedence and geocoding is skipped. Only published, public events from verified active organizations are returned. Each event object conforms to Schema.org Event for use in rich search results and LLM tool responses.","parameters":[{"name":"lat","required":false,"in":"query","description":"Latitude of the search center. Must be provided together with lng. Takes precedence over address fields.","schema":{"type":"number","minimum":-90,"maximum":90,"example":30.2672}},{"name":"lng","required":false,"in":"query","description":"Longitude of the search center. Must be provided together with lat. Takes precedence over address fields.","schema":{"type":"number","minimum":-180,"maximum":180,"example":-97.7431}},{"name":"zip","required":false,"in":"query","schema":{"type":"string","example":"78701"},"description":"Postal/ZIP code. Used for geocoding when lat+lng are not provided."},{"name":"city","required":false,"in":"query","schema":{"type":"string","example":"Austin"},"description":"City name. Used for geocoding when lat+lng are not provided."},{"name":"state","required":false,"in":"query","schema":{"type":"string","example":"TX"},"description":"State or province. Used for geocoding when lat+lng are not provided."},{"name":"country","required":false,"in":"query","schema":{"type":"string","example":"US"},"description":"Country name or ISO code. Used for geocoding when lat+lng are not provided."},{"name":"radius","required":false,"in":"query","description":"Search radius in miles.","schema":{"type":"number","default":25,"minimum":1,"maximum":100,"example":25}},{"name":"days","required":false,"in":"query","description":"Limit results to events whose startDate falls within the next N days.","schema":{"type":"integer","minimum":1,"example":7}},{"name":"page","required":false,"in":"query","description":"Page number for paginated results.","schema":{"type":"integer","default":1,"minimum":1,"example":1}},{"name":"pageSize","required":false,"in":"query","description":"Number of results per page.","schema":{"type":"integer","default":20,"minimum":1,"maximum":50,"example":20}}],"responses":{"200":{"description":"Upcoming public events near the requested location, sorted by distance then start date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventSearchResponseDto"},"example":{"meta":{"query":{"city":"Austin","state":"TX","radiusMiles":25},"resolvedLocation":{"lat":30.2672,"lng":-97.7431,"displayName":"Austin, TX, USA"},"self":"https://zinda.org/api/v1/events/search","totalCount":2,"page":1,"pageSize":20,"pageCount":1,"description":"2 upcoming public events within 25 miles of Austin, TX, USA"},"events":[{"@context":"https://schema.org","@type":"Event","id":101,"name":"Charity 5K Run","description":"Join us for a fun run benefiting the Central Texas Food Bank. All ages welcome.","startDate":"2026-05-10T14:00:00.000Z","endDate":"2026-05-10T17:00:00.000Z","startTime":"9:00 AM","endTime":"12:00 PM","timeZone":"America/Chicago","location":"Zilker Park, Austin, TX 78704","latitude":30.2669,"longitude":-97.7728,"url":"https://zinda.org/app/events/101","distanceMiles":2.1,"acceptingDonations":true,"organizer":{"id":42,"name":"Austin Community Foundation","logo":"https://cdn.zinda.org/logos/acf.png","url":"https://zinda.org/app/organizations/42"},"tags":["fundraiser","community","fitness"]},{"@context":"https://schema.org","@type":"Event","id":108,"name":"Back to School Supply Drive","description":"Help us collect school supplies for students in need across Travis County.","startDate":"2026-05-18T18:00:00.000Z","endDate":"2026-05-18T21:00:00.000Z","startTime":"1:00 PM","endTime":"4:00 PM","timeZone":"America/Chicago","location":"Austin Public Library, 710 W César Chávez St, Austin, TX 78701","latitude":30.2686,"longitude":-97.7496,"url":"https://zinda.org/app/events/108","distanceMiles":4.7,"acceptingDonations":false,"organizer":{"id":55,"name":"Literacy Coalition of Central Texas","logo":"https://cdn.zinda.org/logos/lcct.png","url":"https://zinda.org/app/organizations/55"},"tags":["education","community","volunteering"]}]}}}},"400":{"description":"Missing or invalid location parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"},"example":{"statusCode":400,"message":"At least one location parameter is required: lat+lng, zip, city, state, or country.","error":"Bad Request"}}}},"429":{"description":"Rate limit exceeded. Maximum 60 requests per minute per IP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"},"example":{"statusCode":429,"message":"ThrottlerException: Too Many Requests","error":"Too Many Requests"}}}}},"tags":["Public API"]}}},"info":{"title":"Zinda Public API","description":"Public API for discovering upcoming community and nonprofit events by location. No authentication required. Results include Schema.org Event markup for use in rich search results and LLM tool responses.","version":"1.0","contact":{"name":"Zinda","url":"https://zinda.org","email":"hello@zinda.org"},"license":{"name":"Terms of Use","url":"https://zinda.org/terms"},"termsOfService":"https://zinda.org/terms"},"tags":[],"servers":[{"url":"https://zinda.org","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"components":{"schemas":{"ErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"integer","example":400,"description":"HTTP status code"},"message":{"type":"string","example":"At least one location parameter is required: lat+lng, zip, city, state, or country.","description":"Human-readable error message"},"error":{"type":"string","example":"Bad Request","description":"HTTP status text"}},"required":["statusCode","message","error"]},"EventOrganizerDto":{"type":"object","properties":{"id":{"type":"integer","example":42,"description":"Organizer organization ID"},"name":{"type":"string","example":"Austin Community Foundation","description":"Organization name"},"logo":{"type":"string","format":"uri","example":"https://cdn.zinda.org/logos/acf.png","description":"Organization logo URL"},"url":{"type":"string","format":"uri","example":"https://zinda.org/app/organizations/42","description":"Organization profile URL on Zinda"}},"required":["id","name","logo","url"]},"PublicEventDto":{"type":"object","properties":{"id":{"type":"integer","example":101,"description":"Unique event ID"},"name":{"type":"string","example":"Charity 5K Run","description":"Event name"},"description":{"type":"string","nullable":true,"example":"Join us for a fun run benefiting the Central Texas Food Bank. All ages welcome.","description":"Event description, truncated to 500 characters"},"startDate":{"type":"string","format":"date-time","example":"2026-05-10T14:00:00.000Z","description":"Event start date and time in UTC (ISO 8601)"},"endDate":{"type":"string","format":"date-time","example":"2026-05-10T17:00:00.000Z","description":"Event end date and time in UTC (ISO 8601)"},"startTime":{"type":"string","nullable":true,"example":"9:00 AM","description":"Start time as a display string in the event timezone"},"endTime":{"type":"string","nullable":true,"example":"12:00 PM","description":"End time as a display string in the event timezone"},"timeZone":{"type":"string","nullable":true,"example":"America/Chicago","description":"IANA timezone identifier for the event location"},"location":{"type":"string","nullable":true,"example":"Zilker Park, Austin, TX 78704","description":"Free-text event location description"},"latitude":{"type":"number","nullable":true,"minimum":-90,"maximum":90,"example":30.2669,"description":"Event latitude"},"longitude":{"type":"number","nullable":true,"minimum":-180,"maximum":180,"example":-97.7728,"description":"Event longitude"},"url":{"type":"string","format":"uri","example":"https://zinda.org/app/events/101","description":"Canonical event URL on Zinda"},"distanceMiles":{"type":"number","example":2.1,"description":"Distance in miles from the search location to the event, rounded to 2 decimal places"},"acceptingDonations":{"type":"boolean","example":true,"description":"Whether the event is configured to accept donations"},"organizer":{"description":"Organization hosting the event","allOf":[{"$ref":"#/components/schemas/EventOrganizerDto"}]},"tags":{"example":["fundraiser","community","fitness"],"description":"Tags associated with the event","type":"array","items":{"type":"string"}},"@context":{"type":"string","enum":["https://schema.org"],"example":"https://schema.org","description":"Schema.org context — always \"https://schema.org\""},"@type":{"type":"string","enum":["Event"],"example":"Event","description":"Schema.org type — always \"Event\""}},"required":["id","name","description","startDate","endDate","startTime","endTime","timeZone","location","latitude","longitude","url","distanceMiles","acceptingDonations","organizer","tags","@context","@type"]},"SearchQueryDto":{"type":"object","properties":{"lat":{"type":"number","nullable":true,"example":30.2672,"description":"Resolved latitude used for the search"},"lng":{"type":"number","nullable":true,"example":-97.7431,"description":"Resolved longitude used for the search"},"zip":{"type":"string","nullable":true,"example":"78701","description":"ZIP code supplied by caller"},"city":{"type":"string","nullable":true,"example":"Austin","description":"City supplied by caller"},"state":{"type":"string","nullable":true,"example":"TX","description":"State supplied by caller"},"country":{"type":"string","nullable":true,"example":"US","description":"Country supplied by caller"},"radiusMiles":{"type":"number","example":25,"description":"Search radius in miles applied to the query"},"days":{"type":"integer","nullable":true,"example":7,"description":"Day window filter applied, if provided"}},"required":["lat","lng","zip","city","state","country","radiusMiles","days"]},"ResolvedLocationDto":{"type":"object","properties":{"lat":{"type":"number","example":30.2672,"description":"Geocoded latitude"},"lng":{"type":"number","example":-97.7431,"description":"Geocoded longitude"},"displayName":{"type":"string","example":"Austin, TX, USA","description":"Human-readable location name returned by geocoder or derived from input"}},"required":["lat","lng","displayName"]},"SearchMetaDto":{"type":"object","properties":{"query":{"description":"Parameters actually used for this search","allOf":[{"$ref":"#/components/schemas/SearchQueryDto"}]},"resolvedLocation":{"description":"Resolved coordinates and display name for the search center","allOf":[{"$ref":"#/components/schemas/ResolvedLocationDto"}]},"self":{"type":"string","format":"uri","example":"https://zinda.org/api/v1/events/search","description":"Canonical URL of this endpoint"},"totalCount":{"type":"integer","example":2,"description":"Total number of matching events across all pages"},"page":{"type":"integer","example":1,"description":"Current page number"},"pageSize":{"type":"integer","example":20,"description":"Number of results per page"},"pageCount":{"type":"integer","example":1,"description":"Total number of pages"},"description":{"type":"string","example":"2 upcoming public events within 25 miles of Austin, TX, USA","description":"Plain-language summary of results, suitable for display or LLM responses"}},"required":["query","resolvedLocation","self","totalCount","page","pageSize","pageCount","description"]},"EventSearchResponseDto":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/SearchMetaDto"},"events":{"type":"array","items":{"$ref":"#/components/schemas/PublicEventDto"}}},"required":["meta","events"]}}},"externalDocs":{"description":"Zinda Documentation","url":"https://zinda.org/docs"}}