Este documento descreve o que você precisa saber para usar a API Google Civic Information. Consulte as Perguntas frequentes da API Civic Info, que tem algumas informações básicas sobre a API e perguntas frequentes do nosso fórum de usuários. Além disso, confira abaixo exemplos de como pesquisar informações sobre eleitores durante uma eleição.
Como identificar seu aplicativo para o Google
Seu aplicativo precisa se identificar sempre que enviar uma solicitação para a API Google Civic Information, incluindo uma chave de API em cada solicitação.
Como receber e usar uma chave de API
Para adquirir uma chave de API:
- Abra a página Credenciais no Console da API.
-
Essa API aceita dois tipos de credenciais.
Crie as credenciais que sejam adequadas ao seu projeto:
-
OAuth 2.0: sempre que seu aplicativo solicitar dados particulares do usuário, ele deverá enviar um token OAuth 2.0 junto da solicitação. Primeiro, seu aplicativo envia um ID de cliente e, possivelmente, uma chave secreta do cliente para obter um token. É possível gerar credenciais OAuth 2.0 para aplicativos da Web, contas de serviço ou aplicativos instalados.
Observação:como essa API não tem métodos que exigem autorização do OAuth 2.0, talvez seja necessário apenas receber as chaves da API, que estão descritas abaixo. No entanto, se seu aplicativo chamar outras APIs que exigem autorização de usuário, as credenciais do OAuth 2.0 serão necessárias.
Para mais informações, leia a documentação do OAuth 2.0.
-
Chaves de API: uma solicitação que não fornece um token OAuth 2.0 precisa enviar uma chave de API. A chave identifica seu projeto e fornece acesso à API, à cota e aos relatórios.
A API é compatível com diversos tipos de restrições em chaves de API. Se a chave de API de que você precisa ainda não existe, crie uma no Console clicando em Criar credenciais > Chave de API. É possível restringir a chave antes de usá-la na produção clicando em Restringir chave e selecionando uma das Restrições.
-
Para proteger as chaves de API, siga as práticas recomendadas para usar as chaves de API com segurança.
Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey a todos os URLs de solicitação.
É seguro incorporar a chave de API a URLs. Não é necessário codificá-la.
Restrições da chave de API
Por padrão, a chave de API não tem restrições, o que é inseguro se qualquer pessoa puder ler essa chave (se ela estiver em um navegador, por exemplo) ou acessar o dispositivo em que ela está. Recomendamos que você coloque uma restrição nessa chave de API para impedir o uso não autorizado.
Para adicionar uma restrição, clique em Restringir chave na caixa de diálogo Chave de API criada. O painel de configuração da chave de API vai aparecer:
O tipo de restrição selecionado depende das necessidades do aplicativo:
- Os aplicativos da Web que interagem diretamente com a API (ou seja, não por back-end ou middleware) precisam adicionar uma restrição de referenciadores HTTP. No entanto, esses aplicativos expõem a chave de API publicamente. Use um esquema de autenticação de conta de serviço.
- Os aplicativos de back-end que não podem oferecer suporte a contas de serviço (por exemplo, dispositivos incorporados que não têm um idioma com suporte na biblioteca de cliente) precisam adicionar uma restrição de endereços IP para evitar o uso de clientes em diferentes endereços IP.
- Os aplicativos Android precisam adicionar uma restrição de apps Android e o nome do pacote e a impressão digital do certificado de assinatura SHA-1.
- Os aplicativos iOS precisam adicionar uma restrição de apps iOS e incluir todos os identificadores de pacote do iOS para restringir as chamadas de API a esses pacotes.
Para os testes, convém não colocar qualquer restrição. No entanto, é recomendável adicionar uma restrição a essa chave ou excluí-la depois de implantar o aplicativo na produção.
Exemplo de electionQuery
Confira um exemplo (usando a versão "v2" da API) de como chamar a API electionQuery para receber uma lista de IDs de eleições válidos e, em seguida, usar a API voterInfoQuery com o endereço registrado de um eleitor para receber informações sobre uma eleição selecionada.
Use electionQuery para receber uma lista de IDs de eleições válidos:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
Resposta da electionQuery:
{
"kind": "civicinfo#electionsqueryresponse",
"elections": [
{
"id": "2000",
"name": "VIP Test Election",
"electionDay": "2013-06-06"
},
{
"id": "2124",
"name": "Rhode Island 2012 Primary Election",
"electionDay": "2012-09-11"
},
{
"id": "2126",
"name": "Delaware 2012 Primary Election",
"electionDay": "2012-09-11"
}
]
}voterInfoQuery usando curl
Use curl para enviar uma solicitação voterInfoQuery
para o ID de eleição de teste VIP 2000 e o eleitor no endereço (de teste) 340 Main St, Venice, CA 90291.
Consulte a resposta de voterInfoQuery.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
voterInfoQuery usando a biblioteca de cliente da API do Google para JavaScript
Este exemplo emite a mesma voterInfoQuery do exemplo anterior do curl, mas usa a biblioteca de cliente JavaScript. A resposta voterInfoQuery é igual à resposta de exemplo do curl.
<!doctype html> <html> <head> <script> /** * Build and execute request to look up voter info for provided address. * @param {string} address Address for which to fetch voter info. * @param {function(Object)} callback Function which takes the * response object as a parameter. */ function lookup(address, callback) { /** * Election ID for which to fetch voter info. * @type {number} */ var electionId = 2000; /** * Request object for given parameters. * @type {gapi.client.HttpRequest} */ var req = gapi.client.request({ 'path' : '/civicinfo/v2/voterinfo', 'params' : {'electionId' : electionId, 'address' : address} }); req.execute(callback); } /** * Render results in the DOM. * @param {Object} response Response object returned by the API. * @param {Object} rawResponse Raw response from the API. */ function renderResults(response, rawResponse) { var el = document.getElementById('results'); if (!response || response.error) { el.appendChild(document.createTextNode( 'Error while trying to fetch polling place')); return; } var normalizedAddress = response.normalizedInput.line1 + ' ' + response.normalizedInput.city + ', ' + response.normalizedInput.state + ' ' + response.normalizedInput.zip; if (response.pollingLocations.length > 0) { var pollingLocation = response.pollingLocations[0].address; var pollingAddress = pollingLocation.locationName + ', ' + pollingLocation.line1 + ' ' + pollingLocation.city + ', ' + pollingLocation.state + ' ' + pollingLocation.zip; var normEl = document.createElement('strong'); normEl.appendChild(document.createTextNode( 'Polling place for ' + normalizedAddress + ': ')); el.appendChild(normEl); el.appendChild(document.createTextNode(pollingAddress)); } else { el.appendChild(document.createTextNode( 'Could not find polling place for ' + normalizedAddress)); } } /** * Initialize the API client and make a request. */ function load() { gapi.client.setApiKey('YOUR API KEY GOES HERE'); lookup('1263 Pacific Ave. Kansas City KS', renderResults); } </script> <script src="https://apis.google.com/js/client.js?onload=load"></script> </head> <body> <div id="results"></div> </body> </html>
Resposta de voterInfoQuery
{ "kind": "civicinfo#voterinforesponse", "status": "success", "election": { "id": "2000", "name": "VIP Test Election", "electionDay": "2025-06-06", "ocdDivisionId": "ocd-division/country:us" }, "normalizedInput": { "line1": "340 Main Street", "city": "Venice", "state": "CA", "zip": "90291" }, "pollingLocations": [ { "address": { "locationName": "WESTMINSTER AVENUE ELEMENTARY SCHOOL", "line1": "1010 ABBOT KINNEY BLVD", "city": "VENICE", "state": "CA", "zip": "90291" }, "pollingHours": "", "latitude": 33.9919351, "longitude": -118.4722031, "startDate": "2024-03-05", "endDate": "2024-03-05", "sources": [ { "name": "Voting Information Project", "official": true } ] }, { "address": { "locationName": "POP UP VOTE CENTER 5", "line1": "12400 IMPERIAL HWY", "city": "NORWALK", "state": "CA", "zip": "90650" }, "latitude": 33.915989, "longitude": -118.0677283, "sources": [ { "name": "Voting Information Project", "official": true } ] } ], "dropOffLocations": [ { "address": { "locationName": "FLEX VOTE CENTER 9", "line1": "12400 IMPERIAL HWY", "city": "NORWALK", "state": "CA", "zip": "90650" }, "latitude": 33.915989, "longitude": -118.0677283, "sources": [ { "name": "Voting Information Project", "official": true } ] }, ], "contests": [ { "type": "General", "ballotTitle": "UNITED STATES REPRESENTATIVE, 36th District", "district": { "name": "36TH US CONGRESSIONAL", "scope": "congressional" }, "numberElected": "1", "numberVotingFor": "1", "ballotPlacement": "103", "sources": [ { "name": "Voting Information Project", "official": true } ], "candidates": [ { "name": "ARIANA HAKAMI", "party": "Party Preference: Republican" }, { "name": "CLAIRE RAGGE ANDERSON", "party": "Party Preference: None" }, { "name": "MELISSA TOOMIM", "party": "Party Preference: Republican" }, { "name": "TED W. LIEU", "party": "Party Preference: Democratic" } ] }, { "type": "ballot-measure", "ballotTitle": "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA", "district": { "name": "CITY OF LOS ANGELES", "scope": "citywide" }, "ballotPlacement": "116", "referendumTitle": "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA", "referendumText": "CITY MOBILITY PLAN STREET IMPROVEMENT MEASURES. INITIATIVE ORDINANCE HLA. Shall an ordinance providing that when the City of Los Angeles makes a qualifying improvement to a City-owned street (e.g., a paving project), the City must also install certain street enhancements described in the City's Mobility Plan network of pedestrian, bicycle, transit, and vehicle routes; and requiring the City to provide publicly accessible information regarding street improvements; be adopted?", "referendumPassageThreshold": "MAJORITY OF VOTES CAST", "referendumBallotResponses": [ "YES", "NO" ], "sources": [ { "name": "Voting Information Project", "official": true } ] }, { "type": "General", "ballotTitle": "DISTRICT ATTORNEY", "district": { "name": "LOS ANGELES COUNTY", "scope": "countywide" }, "numberElected": "1", "numberVotingFor": "1", "ballotPlacement": "129", "sources": [ { "name": "Voting Information Project", "official": true } ], "candidates": [ { "name": "GEORGE GASCÓN" }, { "name": "JONATHAN HATAMI" }, { "name": "NATHAN HOCHMAN" }, { "name": "DEBRA ARCHULETA" }, { "name": "JEFF CHEMERINSKY" }, { "name": "ERIC SIDDALL" }, { "name": "MARIA RAMIREZ" }, { "name": "DAN KAPELOVITZ" }, { "name": "LLOYD \"BOBCAT\" MASSON" }, { "name": "JOHN MCKINNEY" }, { "name": "CRAIG J. MITCHELL" }, { "name": "DAVID S. MILTON" } ] } ], "state": [ { "name": "California", "electionAdministrationBody": { "name": "Secretary of State", "electionInfoUrl": "https://www.sos.ca.gov/elections/", "electionRegistrationUrl": "https://registertovote.ca.gov/?t=s", "electionRegistrationConfirmationUrl": "https://voterstatus.sos.ca.gov", "absenteeVotingInfoUrl": "https://elections.cdn.sos.ca.gov/vote-by-mail/replacement-application.pdf", "votingLocationFinderUrl": "https://voterstatus.sos.ca.gov", "ballotInfoUrl": "https://www.sos.ca.gov/elections/ballot-status/wheres-my-ballot/", "correspondenceAddress": { "line1": "1500 11th Street, 5th Floor", "city": "Sacramento", "state": "California", "zip": "95814" } }, "local_jurisdiction": { "name": "Los Angeles", "electionAdministrationBody": { "name": "Registrar-Recorder/County Clerk", "electionInfoUrl": "http://www.lavote.gov/", "electionRegistrationUrl": "http://registertovote.ca.gov/", "electionRegistrationConfirmationUrl": "https://lavote.gov/vrstatus/", "absenteeVotingInfoUrl": "", "ballotInfoUrl": "http://www.lavote.gov/Locator", "physicalAddress": { "locationName": "Registrar-Recorder/County Clerk", "line1": "12400 Imperial Highway", "city": "Norwalk", "state": "CA", "zip": "90650" } }, "sources": [ { "name": "Voting Information Project", "official": true } ] } } ] }