{"openapi":"3.1.0","info":{"title":"br-elections-mcp REST API","description":"As perguntas do eleitor sobre os dados abertos do TSE, sem dado pessoal. Mesmo envelope das tools MCP: data, not_found, warnings, election, source.","version":"0.1.0"},"paths":{"/polling-place":{"get":{"summary":"Onde voto","description":"Local de votação a partir da UF, zona e seção do título de eleitor. Não aceita nome, CPF ou número do título.","operationId":"polling_place_polling_place_get","parameters":[{"name":"uf","in":"query","required":true,"schema":{"type":"string","description":"Sigla da UF: estados, DF ou ZZ","title":"Uf"},"description":"Sigla da UF: estados, DF ou ZZ"},{"name":"zone","in":"query","required":true,"schema":{"type":"string","description":"Zona eleitoral; aceita zeros à esquerda","title":"Zone"},"description":"Zona eleitoral; aceita zeros à esquerda"},{"name":"section","in":"query","required":true,"schema":{"type":"string","description":"Seção eleitoral; aceita zeros à esquerda","title":"Section"},"description":"Seção eleitoral; aceita zeros à esquerda"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PollingPlaceAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/election":{"get":{"summary":"Quando é a eleição","description":"Data e horário da votação, turnos, cargos em disputa e a fonte oficial. Responde 'quando é a eleição' e 'até que horas posso votar'.","operationId":"election_election_get","parameters":[{"name":"on","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Data no formato AAAA-MM-DD; padrão: hoje","title":"On"},"description":"Data no formato AAAA-MM-DD; padrão: hoje"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectionInfoAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/candidates":{"get":{"summary":"Candidatos","description":"Candidatos de um cargo numa UF (BR para presidente), com filtro por partido ou por nome de urna ou nome civil. Nunca inclui CPF, título de eleitor, data de nascimento ou e-mail.","operationId":"candidates_candidates_get","parameters":[{"name":"uf","in":"query","required":true,"schema":{"type":"string","description":"Sigla da UF: estados, DF ou BR para presidente","title":"Uf"},"description":"Sigla da UF: estados, DF ou BR para presidente"},{"name":"office","in":"query","required":true,"schema":{"type":"string","description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital","title":"Office"},"description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital"},{"name":"party","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Partido, sigla ou número","title":"Party"},"description":"Partido, sigla ou número"},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Trecho do nome de urna ou do nome civil","title":"Name"},"description":"Trecho do nome de urna ou do nome civil"},{"name":"on_ballot_only","in":"query","required":false,"schema":{"type":"boolean","description":"Só candidatos carregados na urna (padrão)","default":true,"title":"On Ballot Only"},"description":"Só candidatos carregados na urna (padrão)"},{"name":"limit","in":"query","required":false,"schema":{"type":"string","description":"Tamanho da página, 1 a 50","default":"50","title":"Limit"},"description":"Tamanho da página, 1 a 50"},{"name":"offset","in":"query","required":false,"schema":{"type":"string","description":"Início da página","default":"0","title":"Offset"},"description":"Início da página"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidatesAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/candidates/by-number":{"get":{"summary":"Ficha do candidato por número","description":"Ficha de um candidato por UF, cargo e número de urna, só entre os candidatos na urna. Inclui vice ou suplentes da chapa, redes sociais declaradas ao TSE e o link da página oficial no DivulgaCandContas. Nunca inclui CPF, título de eleitor, data de nascimento ou e-mail.","operationId":"candidate_by_number_candidates_by_number_get","parameters":[{"name":"uf","in":"query","required":true,"schema":{"type":"string","description":"Sigla da UF: estados, DF ou BR para presidente","title":"Uf"},"description":"Sigla da UF: estados, DF ou BR para presidente"},{"name":"office","in":"query","required":true,"schema":{"type":"string","description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital","title":"Office"},"description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital"},{"name":"number","in":"query","required":true,"schema":{"type":"string","description":"Número que o eleitor digita na urna","title":"Number"},"description":"Número que o eleitor digita na urna"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/candidates/compare":{"get":{"summary":"Comparar candidatos","description":"Compara lado a lado de 2 a 4 candidaturas do mesmo cargo, UF e turno, por sq ou por number, repetido ou separado por vírgula (number=45,13): partido, aliança, situação do registro, destino dos votos, ocupação, chapa, foto, total de bens declarados e links oficiais. Sempre em ordem de número de urna: não ordena por valor, não pontua e não recomenda voto. Sem sq nem number, compara todas as candidaturas na urna quando são de 2 a 4. Nunca inclui CPF, título de eleitor, data de nascimento, idade, gênero, cor/raça, estado civil ou escolaridade.","operationId":"compare_candidates_candidates_compare_get","parameters":[{"name":"uf","in":"query","required":true,"schema":{"type":"string","description":"Sigla da UF: estados, DF ou BR para presidente","title":"Uf"},"description":"Sigla da UF: estados, DF ou BR para presidente"},{"name":"office","in":"query","required":true,"schema":{"type":"string","description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital","title":"Office"},"description":"Cargo de urna: presidente, governador, senador, deputado_federal, deputado_estadual ou deputado_distrital"},{"name":"sq","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"sq_candidato, de 2 a 4, repetido ou separado por vírgula; ou number","title":"Sq"},"description":"sq_candidato, de 2 a 4, repetido ou separado por vírgula; ou number"},{"name":"number","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Número de urna, de 2 a 4, repetido ou separado por vírgula; ou sq","title":"Number"},"description":"Número de urna, de 2 a 4, repetido ou separado por vírgula; ou sq"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidatesComparisonAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/candidates/{sq_candidato}":{"get":{"summary":"Ficha do candidato","description":"Ficha de um candidato pelo sq_candidato. Inclui vice ou suplentes da chapa, redes sociais declaradas ao TSE e o link da página oficial no DivulgaCandContas. Nunca inclui CPF, título de eleitor, data de nascimento ou e-mail.","operationId":"candidate_candidates__sq_candidato__get","parameters":[{"name":"sq_candidato","in":"path","required":true,"schema":{"type":"integer","description":"Número sequencial da candidatura no TSE","title":"Sq Candidato"},"description":"Número sequencial da candidatura no TSE"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"422":{"description":"sq_candidato não numérico"},"503":{"description":"Índice indisponível"}}}},"/polling-places":{"get":{"summary":"Locais de votação da cidade","description":"Locais de votação de um município, com filtro por bairro, nome do local ou endereço, e ordenados pela distância a (lat, lon) quando informados. Para quem não sabe a zona e a seção.","operationId":"polling_places_polling_places_get","parameters":[{"name":"uf","in":"query","required":true,"schema":{"type":"string","description":"Sigla da UF: estados, DF ou ZZ","title":"Uf"},"description":"Sigla da UF: estados, DF ou ZZ"},{"name":"municipality","in":"query","required":true,"schema":{"type":"string","description":"Nome do município ou código TSE","title":"Municipality"},"description":"Nome do município ou código TSE"},{"name":"neighborhood","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bairro, opcional","title":"Neighborhood"},"description":"Bairro, opcional"},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Texto que casa com o nome do local ou o endereço","title":"Query"},"description":"Texto que casa com o nome do local ou o endereço"},{"name":"lat","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Latitude do eleitor, com lon","title":"Lat"},"description":"Latitude do eleitor, com lon"},{"name":"lon","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Longitude do eleitor, com lat","title":"Lon"},"description":"Longitude do eleitor, com lat"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"1 a 50; padrão 20","title":"Limit"},"description":"1 a 50; padrão 20"},{"name":"offset","in":"query","required":false,"schema":{"type":"string","description":"Início da página","default":"0","title":"Offset"},"description":"Início da página"},{"name":"round","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Turno, opcional","title":"Round"},"description":"Turno, opcional"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PollingPlacesAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/municipalities":{"get":{"summary":"Código do município","description":"Código TSE de um município a partir do nome, com ou sem acento, para usar nas outras rotas.","operationId":"municipalities_municipalities_get","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","description":"Nome do município, com ou sem acento","title":"Name"},"description":"Nome do município, com ou sem acento"},{"name":"uf","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sigla da UF, opcional","title":"Uf"},"description":"Sigla da UF, opcional"},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"1 a 50; padrão 10","title":"Limit"},"description":"1 a 50; padrão 10"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MunicipalitiesAnswer"}}}},"400":{"description":"Entrada fora do domínio"},"503":{"description":"Índice indisponível"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CalendarSourceInfo":{"properties":{"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"verified_at":{"type":"string","format":"date","title":"Verified At"}},"type":"object","required":["title","url","verified_at"],"title":"CalendarSourceInfo","description":"The normative act the calendar was curated from (domain-model 3.1)."},"CandidateAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/CandidateData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"CandidateAnswer","description":"Answer of ``get_candidate`` (codebase-design 8.4)."},"CandidateData":{"properties":{"candidate":{"$ref":"#/components/schemas/CandidateProfile"}},"type":"object","required":["candidate"],"title":"CandidateData"},"CandidateListItem":{"properties":{"sq_candidato":{"type":"integer","title":"Sq Candidato","description":"Número sequencial da candidatura no TSE"},"number":{"type":"integer","title":"Number","description":"Número que o eleitor digita na urna"},"ballot_name":{"type":"string","title":"Ballot Name","description":"Nome de urna"},"name":{"type":"string","title":"Name","description":"Nome civil"},"office":{"$ref":"#/components/schemas/Office"},"party":{"$ref":"#/components/schemas/Party"},"federation":{"anyOf":[{"$ref":"#/components/schemas/Federation"},{"type":"null"}]},"coalition":{"anyOf":[{"$ref":"#/components/schemas/Coalition"},{"type":"null"}]},"adjudication_status":{"type":"string","title":"Adjudication Status","description":"Situação de julgamento do registro, como o TSE publica"},"on_ballot":{"type":"boolean","title":"On Ballot","description":"Se o candidato está carregado na urna eletrônica"},"occupation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occupation"},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url","description":"Foto oficial espelhada; nula enquanto não há espelho"},"vote_destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote Destination","description":"Destino dos votos, como o TSE publica ('Válido', 'Anulado sub judice', 'Nulo técnico'); nulo quando o TSE não informa"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Como o TSE publica, sem inferência"}},"type":"object","required":["sq_candidato","number","ballot_name","name","office","party","federation","coalition","adjudication_status","on_ballot","occupation","photo_url","vote_destination","gender"],"title":"CandidateListItem","description":"A listed candidate, including the gender-only exception in ADR 0004.\n\nRace/color, marital status and education remain profile-only."},"CandidateProfile":{"properties":{"sq_candidato":{"type":"integer","title":"Sq Candidato","description":"Número sequencial da candidatura no TSE"},"number":{"type":"integer","title":"Number","description":"Número que o eleitor digita na urna"},"ballot_name":{"type":"string","title":"Ballot Name","description":"Nome de urna"},"name":{"type":"string","title":"Name","description":"Nome civil"},"office":{"$ref":"#/components/schemas/Office"},"party":{"$ref":"#/components/schemas/Party"},"federation":{"anyOf":[{"$ref":"#/components/schemas/FederationDetail"},{"type":"null"}]},"coalition":{"anyOf":[{"$ref":"#/components/schemas/CoalitionDetail"},{"type":"null"}]},"adjudication_status":{"type":"string","title":"Adjudication Status","description":"Situação de julgamento do registro, como o TSE publica"},"on_ballot":{"type":"boolean","title":"On Ballot","description":"Se o candidato está carregado na urna eletrônica"},"occupation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occupation"},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url","description":"Foto oficial espelhada; nula enquanto não há espelho"},"vote_destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote Destination","description":"Destino dos votos, como o TSE publica ('Válido', 'Anulado sub judice', 'Nulo técnico'); nulo quando o TSE não informa"},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"Como o TSE publica, sem inferência"},"round":{"type":"integer","title":"Round","description":"Turno a que a ficha se refere"},"social_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Social Name","description":"Nome social, quando declarado"},"nomination_kind":{"type":"string","enum":["partido_isolado","federacao","coligacao"],"title":"Nomination Kind"},"race_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Race Color","description":"Como o TSE publica, sem inferência"},"marital_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Marital Status","description":"Como o TSE publica, sem inferência"},"education":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Education","description":"Como o TSE publica, sem inferência"},"running_mates":{"items":{"$ref":"#/components/schemas/RunningMate"},"type":"array","title":"Running Mates","description":"Vice ou suplentes da chapa (mesmo número); vazia para deputados"},"social_links":{"items":{"type":"string"},"type":"array","title":"Social Links","description":"Redes sociais declaradas ao TSE"},"divulgacandcontas_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Divulgacandcontas Url","description":"Página oficial da candidatura no DivulgaCandContas, para abrir no navegador"}},"type":"object","required":["sq_candidato","number","ballot_name","name","office","party","federation","coalition","adjudication_status","on_ballot","occupation","photo_url","vote_destination","gender","round","social_name","nomination_kind","race_color","marital_status","education","running_mates","social_links","divulgacandcontas_url"],"title":"CandidateProfile","description":"One candidate as ``get_candidate`` shows it (codebase-design 8.4): the list fields\nplus the ones that exist only in the individual profile. ``gender``, ``race_color``,\n``marital_status`` and ``education`` come exactly as the TSE publishes them."},"CandidatesAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/CandidatesData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"CandidatesAnswer","description":"Answer of ``list_candidates`` (codebase-design 8.3). An empty list is data, never\n``not_found``."},"CandidatesComparisonAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/CandidatesComparisonData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"CandidatesComparisonAnswer","description":"Answer of ``compare_candidates`` (codebase-design 8.7). ``source`` is the candidates\nfile; the declared assets come from a second file, cited in ``data.assets_source``."},"CandidatesComparisonData":{"properties":{"round":{"type":"integer","title":"Round","description":"Turno a que a comparação se refere"},"uf":{"type":"string","title":"Uf"},"office":{"$ref":"#/components/schemas/Office"},"candidates":{"items":{"$ref":"#/components/schemas/ComparedCandidate"},"type":"array","title":"Candidates","description":"De 2 a 4 candidaturas na urna, sempre em ordem de número de urna, nunca por valor"},"missing":{"items":{"$ref":"#/components/schemas/MissingCandidacy"},"type":"array","title":"Missing","description":"Candidaturas pedidas que ficaram de fora; pode ser vazia"},"assets_note":{"type":"string","title":"Assets Note","description":"Ressalva fixa sobre os bens declarados, em PT-BR"},"assets_source":{"$ref":"#/components/schemas/Source","description":"Fonte dos bens declarados"}},"type":"object","required":["round","uf","office","candidates","missing","assets_note","assets_source"],"title":"CandidatesComparisonData"},"CandidatesData":{"properties":{"round":{"type":"integer","title":"Round","description":"Turno a que a resposta se refere"},"candidates":{"items":{"$ref":"#/components/schemas/CandidateListItem"},"type":"array","title":"Candidates"},"total":{"type":"integer","title":"Total","description":"Total de candidatos que casam com o filtro, sem paginação"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"}},"type":"object","required":["round","candidates","total","limit","offset"],"title":"CandidatesData"},"Coalition":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"Coalition"},"CoalitionDetail":{"properties":{"name":{"type":"string","title":"Name"},"composition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Composition","description":"Partidos da coligação, como o TSE publica"}},"type":"object","required":["name","composition"],"title":"CoalitionDetail"},"ComparedAssets":{"properties":{"state":{"type":"string","enum":["declarados","declarou_nao_possuir","sem_informacao"],"title":"State","description":"declarados: há bens publicados pelo TSE; declarou_nao_possuir: a candidatura declarou não ter bens; sem_informacao: nenhum dos dois"},"total":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total","description":"Soma dos bens declarados ao TSE, em reais, como declarados; nula fora de 'declarados'"}},"type":"object","required":["state","total"],"title":"ComparedAssets","description":"The declared assets of one compared candidacy: the total only, as declared (ADR 0008)."},"ComparedCandidate":{"properties":{"sq_candidato":{"type":"integer","title":"Sq Candidato","description":"Número sequencial da candidatura no TSE"},"number":{"type":"integer","title":"Number","description":"Número que o eleitor digita na urna"},"ballot_name":{"type":"string","title":"Ballot Name","description":"Nome de urna"},"name":{"type":"string","title":"Name","description":"Nome civil"},"office":{"$ref":"#/components/schemas/Office"},"party":{"$ref":"#/components/schemas/Party"},"federation":{"anyOf":[{"$ref":"#/components/schemas/FederationDetail"},{"type":"null"}]},"coalition":{"anyOf":[{"$ref":"#/components/schemas/CoalitionDetail"},{"type":"null"}]},"adjudication_status":{"type":"string","title":"Adjudication Status","description":"Situação de julgamento do registro, como o TSE publica"},"on_ballot":{"type":"boolean","title":"On Ballot","description":"Se o candidato está carregado na urna eletrônica"},"occupation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occupation"},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Photo Url","description":"Foto oficial espelhada; nula enquanto não há espelho"},"vote_destination":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote Destination","description":"Destino dos votos, como o TSE publica ('Válido', 'Anulado sub judice', 'Nulo técnico'); nulo quando o TSE não informa"},"social_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Social Name","description":"Nome social, quando declarado"},"nomination_kind":{"type":"string","enum":["partido_isolado","federacao","coligacao"],"title":"Nomination Kind"},"vote_destination_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vote Destination Note","description":"Uma linha que explica vote_destination ao eleitor; nula para um valor que o serviço não conhece"},"running_mates":{"items":{"$ref":"#/components/schemas/RunningMate"},"type":"array","title":"Running Mates","description":"Vice ou suplentes da chapa (mesmo número), só nome e partido; vazia para deputados"},"social_links":{"items":{"type":"string"},"type":"array","title":"Social Links","description":"Redes sociais declaradas ao TSE"},"divulgacandcontas_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Divulgacandcontas Url","description":"Página oficial da candidatura no DivulgaCandContas, com cada bem declarado"},"assets":{"$ref":"#/components/schemas/ComparedAssets"}},"type":"object","required":["sq_candidato","number","ballot_name","name","office","party","federation","coalition","adjudication_status","on_ballot","occupation","photo_url","vote_destination","social_name","nomination_kind","vote_destination_note","running_mates","social_links","divulgacandcontas_url","assets"],"title":"ComparedCandidate","description":"One candidacy of ``compare_candidates`` (codebase-design 8.7): the list fields, the\nalliance with its composition, the vote destination with its explanation, the ticket by\nname and party, the links and the declared-assets total. Deliberately without\n``gender``, ``race_color``, ``marital_status`` and ``education``: a comparison is\noutside the gender-only list exception (ADR 0004)."},"CuratedSource":{"properties":{"kind":{"type":"string","const":"curated","title":"Kind","default":"curated"},"calendar_source":{"type":"string","title":"Calendar Source","description":"Título da fonte curada, ex.: a resolução do TSE"},"verified_at":{"type":"string","format":"date","title":"Verified At"},"license":{"type":"string","title":"License","default":"CC-BY"},"attribution":{"type":"string","title":"Attribution","default":"Tribunal Superior Eleitoral - Portal de Dados Abertos"}},"type":"object","required":["calendar_source","verified_at"],"title":"CuratedSource","description":"Source for answers curated from ``data/elections.yaml`` (domain-model 3.6):\n``calendar_source`` replaces ``dataset`` and ``verified_at`` replaces ``generated_at``.\nNever ages, so ``stale`` and ``age_hours`` are absent."},"ElectionInfo":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"round":{"$ref":"#/components/schemas/ElectionRoundInfo"},"voting_hours":{"$ref":"#/components/schemas/VotingHoursInfo"}},"type":"object","required":["id","name","round","voting_hours"],"title":"ElectionInfo","description":"The current election of the calendar, with the round the answer refers to."},"ElectionInfoAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfoData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; sempre vazia aqui"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/CuratedSource"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"ElectionInfoAnswer","description":"Answer of ``election_info`` (codebase-design 8.5). Never ``not_found`` and never stale."},"ElectionInfoData":{"properties":{"id":{"type":"string","title":"Id","description":"Id da eleição no calendário curado, ex.: general-2026"},"name":{"type":"string","title":"Name","description":"Nome da eleição, ex.: Eleições Gerais 2026"},"rounds":{"items":{"$ref":"#/components/schemas/ElectionInfoRound"},"type":"array","title":"Rounds"},"voting_hours":{"$ref":"#/components/schemas/VotingHoursInfo"},"next_round":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfoRound"},{"type":"null"}],"description":"Próximo turno a partir da data consultada, ou nulo após o último turno"},"days_until_next_round":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days Until Next Round","description":"Dias até next_round, ou nulo quando não há próximo turno"},"offices":{"items":{"$ref":"#/components/schemas/Office"},"type":"array","title":"Offices"},"notes":{"items":{"type":"string"},"type":"array","title":"Notes","description":"Avisos curados ao eleitor, em PT-BR; pode ser vazia"},"calendar_source":{"$ref":"#/components/schemas/CalendarSourceInfo"}},"type":"object","required":["id","name","rounds","voting_hours","next_round","days_until_next_round","offices","notes","calendar_source"],"title":"ElectionInfoData","description":"The calendar of the election the answer describes. ``id`` and ``name`` repeat the\nelection's own identity here because ``election`` is null in this answer (there is no\n\"round the answer refers to\"), and a client titling the calendar needs the name."},"ElectionInfoRound":{"properties":{"number":{"type":"integer","title":"Number"},"date":{"type":"string","format":"date","title":"Date"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["number","date"],"title":"ElectionInfoRound"},"ElectionRoundInfo":{"properties":{"number":{"type":"integer","title":"Number"},"date":{"type":"string","format":"date","title":"Date"}},"type":"object","required":["number","date"],"title":"ElectionRoundInfo"},"Federation":{"properties":{"acronym":{"type":"string","title":"Acronym"},"name":{"type":"string","title":"Name"}},"type":"object","required":["acronym","name"],"title":"Federation"},"FederationDetail":{"properties":{"acronym":{"type":"string","title":"Acronym"},"name":{"type":"string","title":"Name"},"composition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Composition","description":"Partidos da federação, como o TSE publica"}},"type":"object","required":["acronym","name","composition"],"title":"FederationDetail"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MissingCandidacy":{"properties":{"requested":{"type":"integer","title":"Requested","description":"O número de urna ou o sq_candidato pedido"},"reason":{"type":"string","enum":["nao_encontrado","fora_da_urna","fora_do_turno"],"title":"Reason","description":"nao_encontrado: nenhuma candidatura do cargo com ele; fora_da_urna: existe no turno, mas não está na urna; fora_do_turno: não disputa o turno respondido"}},"type":"object","required":["requested","reason"],"title":"MissingCandidacy","description":"A requested number or ``sq_candidato`` left out of the comparison, and why."},"MunicipalitiesAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/MunicipalitiesData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"MunicipalitiesAnswer","description":"Answer of ``resolve_municipality`` (codebase-design 8.6).\n\n``election`` is always null: the municipality list refers to no round."},"MunicipalitiesData":{"properties":{"municipalities":{"items":{"$ref":"#/components/schemas/MunicipalityMatch"},"type":"array","title":"Municipalities","description":"Do melhor para o pior `score`; nunca vazia (sem candidato é not_found)"}},"type":"object","required":["municipalities"],"title":"MunicipalitiesData"},"Municipality":{"properties":{"tse_code":{"type":"string","title":"Tse Code","description":"Código TSE, 5 dígitos"},"ibge_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ibge Code","description":"Código IBGE de 7 dígitos; nulo no exterior"},"name":{"type":"string","title":"Name"},"uf":{"type":"string","title":"Uf"}},"type":"object","required":["tse_code","ibge_code","name","uf"],"title":"Municipality"},"MunicipalityMatch":{"properties":{"tse_code":{"type":"string","title":"Tse Code","description":"Código TSE, 5 dígitos"},"ibge_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ibge Code","description":"Código IBGE de 7 dígitos; nulo no exterior"},"name":{"type":"string","title":"Name"},"uf":{"type":"string","title":"Uf"},"score":{"type":"number","title":"Score","description":"1.0 para o nome exato (sem acento e sem diferenciar maiúsculas), menor para nome parcial ou parecido"}},"type":"object","required":["tse_code","ibge_code","name","uf","score"],"title":"MunicipalityMatch","description":"One candidate of ``resolve_municipality``: a municipality with how well it matched."},"NotFound":{"properties":{"reason":{"type":"string","enum":["secao_nao_encontrada","municipio_nao_encontrado","municipio_ambiguo","candidato_nao_encontrado","candidaturas_insuficientes"],"title":"Reason","description":"Motivo, em PT-BR"},"guidance":{"type":"string","title":"Guidance","description":"Orientação ao eleitor, em PT-BR"},"options":{"anyOf":[{"items":{"$ref":"#/components/schemas/MunicipalityMatch"},"type":"array"},{"type":"null"}],"title":"Options","description":"Os municípios que casaram, quando o motivo é municipio_ambiguo"}},"type":"object","required":["reason","guidance"],"title":"NotFound"},"Office":{"type":"string","enum":["presidente","vice_presidente","governador","vice_governador","senador","primeiro_suplente","segundo_suplente","deputado_federal","deputado_estadual","deputado_distrital"],"title":"Office","description":"Cargo de uma candidatura, como registrado no TSE.\n\nBallot offices are the ones the voter chooses directly. The others belong\nto a ticket headed by a ballot office (vice and suplentes share the head's\nballot number). Municipal offices are added when a municipal election\nenters the scope."},"Party":{"properties":{"number":{"type":"integer","title":"Number"},"acronym":{"type":"string","title":"Acronym"},"name":{"type":"string","title":"Name"}},"type":"object","required":["number","acronym","name"],"title":"Party"},"PollingPlace":{"properties":{"number":{"type":"integer","title":"Number"},"name":{"type":"string","title":"Name"},"kind":{"type":"string","title":"Kind","description":"Tipo do local, como o TSE publica, ex.: 'Convencional'"},"address":{"type":"string","title":"Address"},"neighborhood":{"type":"string","title":"Neighborhood"},"postal_code":{"type":"string","title":"Postal Code","description":"CEP, 8 dígitos"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"status":{"type":"string","enum":["ativo","bloqueado"],"title":"Status"},"section_count":{"type":"integer","title":"Section Count","description":"Seções que funcionam neste local, no turno"},"accessible_section_count":{"type":"integer","title":"Accessible Section Count","description":"Dessas, quantas têm acessibilidade"}},"type":"object","required":["number","name","kind","address","neighborhood","postal_code","phone","latitude","longitude","status","section_count","accessible_section_count"],"title":"PollingPlace"},"PollingPlaceAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/PollingPlaceData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"PollingPlaceAnswer","description":"Answer of ``find_polling_place`` (codebase-design 8.1)."},"PollingPlaceData":{"properties":{"municipality":{"$ref":"#/components/schemas/Municipality"},"round":{"type":"integer","title":"Round","description":"Turno a que a resposta se refere"},"zone":{"type":"integer","title":"Zone"},"section":{"type":"integer","title":"Section"},"section_kind":{"type":"string","enum":["principal","agregada"],"title":"Section Kind"},"votes_at_section":{"type":"integer","title":"Votes At Section","description":"Seção em que o eleitor efetivamente vota: a principal, se a dele é agregada"},"voters_in_section":{"type":"integer","title":"Voters In Section"},"accessibility":{"type":"string","enum":["com_acessibilidade","sem_acessibilidade"],"title":"Accessibility"},"place":{"$ref":"#/components/schemas/PollingPlace"},"previous_place":{"anyOf":[{"$ref":"#/components/schemas/PreviousPlace"},{"type":"null"}],"description":"Local anterior, quando a seção foi transferida"}},"type":"object","required":["municipality","round","zone","section","section_kind","votes_at_section","voters_in_section","accessibility","place","previous_place"],"title":"PollingPlaceData"},"PollingPlaceListItem":{"additionalProperties":true,"type":"object"},"PollingPlacesAnswer":{"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/PollingPlacesData"},{"type":"null"}]},"not_found":{"anyOf":[{"$ref":"#/components/schemas/NotFound"},{"type":"null"}]},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Avisos ao eleitor, em PT-BR; pode ser vazia"},"election":{"anyOf":[{"$ref":"#/components/schemas/ElectionInfo"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/Source"}},"type":"object","required":["data","not_found","warnings","election","source"],"title":"PollingPlacesAnswer","description":"Answer of ``search_polling_places`` (codebase-design 8.2)."},"PollingPlacesData":{"properties":{"round":{"type":"integer","title":"Round","description":"Turno a que a resposta se refere"},"municipality":{"$ref":"#/components/schemas/Municipality"},"places":{"items":{"$ref":"#/components/schemas/PollingPlaceListItem"},"type":"array","title":"Places"},"total":{"type":"integer","title":"Total","description":"Total de locais que casam com o filtro, antes do limite"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"guidance":{"type":"string","title":"Guidance","description":"Orientação ao eleitor, em PT-BR"}},"type":"object","required":["round","municipality","places","total","limit","offset","guidance"],"title":"PollingPlacesData"},"PreviousPlace":{"properties":{"number":{"type":"integer","title":"Number"},"name":{"type":"string","title":"Name"},"address":{"type":"string","title":"Address"}},"type":"object","required":["number","name","address"],"title":"PreviousPlace"},"RunningMate":{"properties":{"sq_candidato":{"type":"integer","title":"Sq Candidato"},"office":{"$ref":"#/components/schemas/Office"},"ballot_name":{"type":"string","title":"Ballot Name"},"name":{"type":"string","title":"Name"},"party":{"$ref":"#/components/schemas/Party"}},"type":"object","required":["sq_candidato","office","ballot_name","name","party"],"title":"RunningMate","description":"A vice or substitute of the ticket, with the same ballot number as the head."},"Source":{"properties":{"kind":{"type":"string","const":"dataset","title":"Kind","default":"dataset"},"dataset":{"type":"string","title":"Dataset"},"dataset_url":{"type":"string","title":"Dataset Url"},"file":{"type":"string","title":"File"},"generated_at":{"type":"string","format":"date-time","title":"Generated At","description":"Instante em que o TSE gerou o arquivo (DT_GERACAO + HH_GERACAO)"},"index_built_at":{"type":"string","format":"date-time","title":"Index Built At"},"age_hours":{"type":"number","title":"Age Hours","description":"Idade do dado em horas, calculada a partir de generated_at e do relógio"},"stale":{"type":"boolean","title":"Stale","description":"True quando age_hours > 48 (STALE_AFTER_HOURS)"},"license":{"type":"string","title":"License","default":"CC-BY"},"attribution":{"type":"string","title":"Attribution","default":"Tribunal Superior Eleitoral - Portal de Dados Abertos"}},"type":"object","required":["dataset","dataset_url","file","generated_at","index_built_at","age_hours","stale"],"title":"Source","description":"Where the data came from, required by the CC-BY license (domain-model 3.6)."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VotingHoursInfo":{"properties":{"start":{"type":"string","title":"Start","description":"HH:MM"},"end":{"type":"string","title":"End","description":"HH:MM"},"timezone":{"type":"string","title":"Timezone","description":"Nome IANA, ex.: America/Sao_Paulo"},"label":{"type":"string","title":"Label","description":"Texto para o eleitor, ex.: '8h às 17h (horário de Brasília)'"}},"type":"object","required":["start","end","timezone","label"],"title":"VotingHoursInfo"}}},"servers":[{"url":"/api/v1"}]}