In diesem Dokument erfahren Sie, was Sie für die Verwendung der Google Civic Information API wissen müssen. In den häufig gestellten Fragen zur Civic Info API finden Sie grundlegende Informationen zur API sowie häufig gestellte Fragen aus unserem Nutzerforum. Unten finden Sie außerdem Beispiele für das Abrufen von Wählerinformationen während einer Wahl.
Anwendung für Google identifizieren
Ihre Anwendung muss sich jedes Mal identifizieren, wenn sie eine Anfrage an die Google Civic Information API sendet. Dazu muss bei jeder Anfrage ein API-Schlüssel angegeben werden.
API-Schlüssel erhalten und nutzen
So erhalten Sie einen API-Schlüssel:
- Öffnen Sie in der API Console die Seite Anmeldedaten.
-
Diese API unterstützt zwei Arten von Anmeldedaten.
Erstellen Sie für Ihr Projekt geeignete Anmeldedaten:
-
OAuth 2.0: Wenn Ihre Anwendung private Nutzerdaten anfordert, muss sie zusammen mit der Anfrage ein OAuth 2.0-Token senden. Die Anwendung sendet zuerst eine Client-ID und möglicherweise einen Clientschlüssel, um ein Token zu erhalten. Sie können OAuth 2.0-Anmeldedaten für Webanwendungen, Dienstkonten oder installierte Anwendungen generieren.
Hinweis:Da für diese API keine Methoden erforderlich sind, für die eine OAuth 2.0-Autorisierung erforderlich ist, müssen Sie möglicherweise nur API-Schlüssel abrufen, die unten beschrieben werden. Wenn Ihre Anwendung jedoch andere APIs aufruft, für die eine Nutzerautorisierung erforderlich ist, benötigen Sie weiterhin OAuth 2.0-Anmeldedaten.
Weitere Informationen finden Sie in der OAuth 2.0-Dokumentation.
-
API-Schlüssel: Eine Anfrage, die kein OAuth 2.0-Token bereitstellt, muss einen API-Schlüssel senden. Mit diesem Schlüssel werden Ihr Projekt identifiziert sowie der API-Zugriff, das Kontingent und Berichte bereitgestellt.
Die API unterstützt mehrere Arten von Einschränkungen für API-Schlüssel. Wenn der API-Schlüssel, den Sie benötigen, noch nicht existiert, können Sie ihn in der Konsole erstellen, indem Sie auf Anmeldedaten erstellen > API-Schlüssel klicken. Sie können Einschränkungen für diesen Schlüssel festlegen, bevor Sie ihn in der Produktion einsetzen. Klicken Sie dazu auf Schlüssel einschränken und wählen Sie dann eine der Einschränkungen aus.
-
Folgen Sie zur Wahrung der Sicherheit Ihrer API-Schlüssel den Best Practices zur sicheren Verwendung von API-Schlüsseln.
Nachdem Sie einen API-Schlüssel haben, kann Ihre Anwendung den Abfrageparameter key=yourAPIKey an alle Anfrage-URLs anhängen.
Der API-Schlüssel lässt sich sicher in URLs einbetten. Eine Codierung ist nicht notwendig.
Einschränkungen für API-Schlüssel
Ihr API-Schlüssel ist standardmäßig uneingeschränkt. Das ist unsicher, wenn jeder diesen Schlüssel lesen (z. B. wenn er in einem Browser platziert ist) oder auf das Gerät zugreifen kann, auf dem er sich befindet. Wir empfehlen, für diesen API-Schlüssel eine Einschränkung festzulegen, um eine nicht autorisierte Nutzung zu verhindern.
Wenn Sie eine Einschränkung hinzufügen möchten, klicken Sie im Dialogfeld API-Schlüssel erstellt auf Schlüssel einschränken. Das Konfigurationsfeld API-Schlüssel wird angezeigt:
Welche Art von Einschränkung Sie auswählen, hängt von den Anforderungen Ihrer Anwendung ab:
- Webanwendungen, die direkt mit der API interagieren (d. h. nicht über ein Backend oder eine Middleware), sollten eine Einschränkung für HTTP-Verweis-URLs hinzufügen. Beachten Sie jedoch, dass bei solchen Anwendungen der API-Schlüssel öffentlich zugänglich ist. Verwenden Sie stattdessen ein Authentifizierungsschema für Dienstkonten.
- Backendanwendungen, die Dienstkonten anderweitig nicht unterstützen können (z. B. eingebettete Geräte, für die in der Clientbibliothek keine unterstützte Sprache vorhanden ist), sollten eine IP-Adressbeschränkung hinzufügen, um die Nutzung durch Clients mit verschiedenen IP-Adressen zu verhindern.
- Android-Anwendungen müssen die Einschränkung Android-Apps sowie den Paketnamen und den SHA-1-Fingerabdruck des Signaturzertifikats hinzufügen.
- iOS-Anwendungen sollten eine Einschränkung vom Typ iOS-Apps und alle iOS-Bundle-IDs hinzufügen, um API-Aufrufe auf diese iOS-Bundles zu beschränken.
Bei Tests können Sie auf sämtliche Einschränkungen verzichten. Wir empfehlen jedoch, diesem Schlüssel entweder eine Einschränkung hinzuzufügen oder ihn zu löschen, sobald Sie Ihre Anwendung in der Produktion bereitstellen.
electionQuery-Beispiel
Hier ist ein Beispiel (mit der API-Version „v2“), in dem die electionQuery API aufgerufen wird, um eine Liste gültiger Wahl-IDs zu erhalten, und dann die voterInfoQuery API mit der registrierten Adresse eines Wählers, um Informationen für eine ausgewählte Wahl abzurufen.
Mit electionQuery kannst du eine Liste mit gültigen Wahl-IDs abrufen:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
electionQuery-Antwort:
{
"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 mit curl
Verwenden Sie curl, um eine voterInfoQuery-Anfrage für die VIP-Testwahl-ID 2000 und den Wähler mit der (Test-)Adresse 340 Main St, Venice, CA 90291 zu senden.
Weitere Informationen finden Sie unter voterInfoQuery-Antwort.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
voterInfoQuery mit der Google API-Clientbibliothek für JavaScript
In diesem Beispiel wird dieselbe voterInfoQuery wie im vorherigen Curl-Beispiel ausgeführt, aber die JavaScript-Clientbibliothek wird verwendet. Die voterInfoQuery-Antwort ist mit der Beispielantwort von curl identisch.
<!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>
voterInfoQuery-Antwort
{ "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 } ] } } ] }