Skip to main content
The OpenCouncil API provides programmatic access to city council meetings, transcripts, people, parties, and more. Built on REST principles, it returns JSON responses and uses standard HTTP response codes.

​
Base URL

All API requests are made to: 
https://api.opencouncil.gr/api
For local development: 
http://localhost:3000/api

​
API specification

The complete API specification is available in OpenAPI 3.0 format:
  • Title: City Council API
  • Version: 1.0.0
  • Format: OpenAPI 3.0
  • Location: swagger.yaml in the source repository

​
Core concepts

​
Cities

Cities represent municipalities or regions with council meetings. Each city has:
  • Unique identifier (slug)
  • Localized names (Greek and English)
  • Status: pending, unlisted, or listed
  • Authority type: municipality or region
  • Support for notifications
  • Official support status

​
Meetings

Council meetings contain:
  • Date and time
  • Administrative body (council, committee, or community)
  • Video/audio recordings
  • Transcripts with speaker segments
  • Subjects discussed
  • Release status

​
People and parties

  • People: Council members with roles, party affiliation, and active terms
  • Parties: Political parties with localized names and branding

​
Subjects

Agenda items discussed in meetings, including:
  • Topic categorization
  • Speaker segments
  • Summaries
  • Location data (when applicable)

​
Key features

Hybrid search

Combine traditional text search with semantic search for intelligent results

Pagination

Built-in pagination support for large result sets

Filtering

Filter by city, person, party, topic, date range, and location

Rich data

Access transcripts, summaries, metadata, and relationships

​
Response format

All API responses return JSON with consistent structure:

​
Success responses

{
  "id": "string",
  "name": "string",
  // ... resource fields
}
For collections: 
[
  { "id": "1", "name": "Item 1" },
  { "id": "2", "name": "Item 2" }
]
For paginated endpoints: 
{
  "results": [
    // ... items
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "totalPages": 10
  }
}

​
Error responses

{
  "error": [
    {
      "code": "invalid_type",
      "message": "Expected string, received number",
      "path": ["query"]
    }
  ]
}

​
HTTP status codes

The API uses standard HTTP status codes:
CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters or request body
401Unauthorized - Authentication required
404Not Found - Resource doesn’t exist
500Internal Server Error - Server-side error occurred

​
Data types

​
Common fields

Many resources include these standard fields:
  • id (string): Unique identifier
  • createdAt (datetime): ISO 8601 timestamp of creation
  • updatedAt (datetime): ISO 8601 timestamp of last update
  • cityId (string): Associated city identifier

​
Localized content

Bilingual fields use _en suffix for English:
  • name (string): Greek name
  • name_en (string): English name

​
Timestamps

All timestamps are in ISO 8601 format: 
"2024-01-15T14:30:00Z"

​
Rate limiting

Rate limiting is not currently enforced, but may be implemented in future versions. Monitor the error.code field for RATE_LIMIT_EXCEEDED errors.

​
Technology stack

The API is built with:
  • Framework: Next.js 14 API Routes
  • Database: PostgreSQL with PostGIS extension
  • ORM: Prisma for type-safe database access
  • Validation: Zod schemas for request validation
  • Search: Elasticsearch for full-text and semantic search
  • Authentication: Auth.js (NextAuth v5) with Resend email provider

​
Getting started

1

Explore the API

Start with the Cities endpoint to discover available municipalities
2

Fetch meetings

Use the Meetings endpoint to get council meetings for a city
3

Search content

Try the Search endpoint to find subjects across all meetings
4

Access transcripts

Get detailed transcripts from the Transcripts endpoint

​
Need help?

Build docs developers (and LLMs) love

Get started for freeTalk to us