Ten dokument zawiera informacje, które musisz znać, aby korzystać z Google Civic Information API. Zapoznaj się z najczęstszymi pytaniami dotyczącymi interfejsu Civic Info API, w których znajdziesz podstawowe informacje o tym interfejsie API oraz odpowiedzi na pytania użytkowników z naszego forum. Poniżej znajdziesz przykłady wyszukiwania informacji o wyborach w okresie wyborczym.
Identyfikowanie aplikacji w Google
Aplikacja musi się identyfikować za każdym razem, gdy wysyła żądanie do interfejsu Google Civic Information API, dołączając do każdego żądania klucz interfejsu API.
Uzyskiwanie i używanie klucza interfejsu API
Aby uzyskać klucz interfejsu API:
- W Konsoli interfejsów API otwórz stronę Dane logowania.
-
Ten interfejs API obsługuje 2 rodzaje danych logowania.
Utwórz dane logowania odpowiednie do Twojego projektu:
-
OAuth 2.0: gdy aplikacja prosi o prywatne dane użytkownika, musi przesłać token OAuth 2.0 wraz z żądaniem. Twoja aplikacja najpierw wysyła identyfikator klienta i opcjonalnie tajny klucz klienta, aby uzyskać token. Możesz generować dane logowania OAuth 2.0 dla aplikacji internetowych, kont usługi lub zainstalowanych aplikacji.
Uwaga: ponieważ ten interfejs API nie ma żadnych metod, które wymagają autoryzacji OAuth 2.0, może być konieczne tylko uzyskanie kluczy API, które są opisane poniżej. Jeśli jednak Twoja aplikacja wywołuje inne interfejsy API, które wymagają autoryzacji użytkownika, nadal musisz mieć uprawnienia OAuth 2.0.
Więcej informacji znajdziesz w dokumentacji OAuth 2.0.
-
Klucze interfejsu API: Żądanie, które nie zawiera tokena OAuth 2.0, musi zawierać klucz interfejsu API. Klucz identyfikuje projekt i zapewnia dostęp do interfejsu API, limitów oraz raportów.
Interfejs API obsługuje kilka typów ograniczeń kluczy API. Jeśli klucz interfejsu API, którego potrzebujesz, nie istnieje, utwórz go w Konsoli, klikając Utwórz dane logowania > Klucz interfejsu API. Możesz ograniczyć klucz przed jego użyciem w środowisku produkcyjnym. Aby to zrobić, kliknij Ogranicz klucz i wybierz jedną z opcji Ograniczenia.
-
Aby zabezpieczyć klucze interfejsu API, postępuj zgodnie ze sprawdzonymi metodami korzystania z kluczy interfejsu API.
Gdy uzyskasz klucz interfejsu API, Twoja aplikacja będzie mogła dołączać parametry zapytania key=yourAPIKey do adresów URL wszystkich żądań.
Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.
Ograniczenia klucza interfejsu API
Klucz API jest domyślnie nieograniczony, co jest niebezpieczne, jeśli ktoś może odczytać ten klucz (jeśli jest umieszczony na przykład w przeglądarce) lub uzyskać dostęp do urządzenia, na którym jest umieszczony. Zalecamy nałożenie ograniczenia na ten klucz interfejsu API, aby zapobiec nieautoryzowanemu użyciu.
Aby dodać ograniczenie, w oknie Utworzono klucz API kliknij Ogranicz klucz. Wyświetli się panel konfiguracji klucza API:
Wybrany typ ograniczenia zależy od potrzeb aplikacji:
- Aplikacje internetowe, które bezpośrednio współpracują z interfejsem API (czyli nie przez żadne oprogramowanie pośredniczące ani pośrednie), powinny dodać ograniczenie dotyczące adresów odsyłających HTTP. Pamiętaj jednak, że takie aplikacje będą publicznie udostępniać klucz interfejsu API. Zamiast tego zalecamy używanie schematu uwierzytelniania konta usługi.
- Aplikacje backendowe, które nie mogą inaczej obsługiwać kont usług (np. urządzenia wbudowane, które nie mają obsługiwanego języka w bibliotece klienta), powinny dodać ograniczenie adresów IP, aby chronić przed korzystaniem z nich przez klientów o różnych adresach IP.
- Aplikacje na Androida powinny dodać ograniczenie Aplikacje na Androida oraz dodać nazwę pakietu i odcisk cyfrowy certyfikatu podpisującego SHA-1.
- Aplikacje na iOS powinny dodać ograniczenie dotyczące aplikacji na iOS oraz dodać identyfikatory pakietów na iOS, aby ograniczyć wywołania interfejsu API do tych pakietów.
Podczas testowania możesz nie chcieć nakładać żadnych ograniczeń. Zalecamy jednak dodanie ograniczenia do tego klucza lub jego usunięcie po wdrożeniu aplikacji w wersji produkcyjnej.
Przykład zapytania o wybory
Oto przykład wywołania interfejsu API (w wersji 2) w celu uzyskania listy prawidłowych identyfikatorów wyborów: electionQuery, a następnie użycia interfejsu API voterInfoQuery z zarejestrowanym adresem wyborcy w celu uzyskania informacji o wybranym wyborach.
Użyj zapytania electionQuery, aby uzyskać listę prawidłowych identyfikatorów wyborów:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
Odpowiedź na zapytanie 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"
}
]
}Zapytanie voterInfoQuery z wykorzystaniem curl
Użyj adresu curl, aby wysłać prośbę o wyświetlenie informacji o wyborcach (query: voterInfoQuery) dla testowego adresu wyborczego 340 Main St, Venice, CA 90291 o identyfikatorze wyborów 2000.
Możesz zapoznać się z odpowiedzią na zapytanie voterInfoQuery.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
voterInfoQuery za pomocą biblioteki klienta Google API dla JavaScriptu
W tym przykładzie używamy tego samego zapytania voterInfoQuery co w poprzednim przykładzie polecenia curl, ale z biblioteką JavaScript dla klienta. Odpowiedź na zapytanie voterInfoQuery jest taka sama jak w przykładowej odpowiedzi 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>
Odpowiedź na zapytanie 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 } ] } } ] }