Bu belgede, Google Civic Information API'yi kullanmak için bilmeniz gerekenler açıklanmaktadır. API hakkında bazı temel bilgiler ve kullanıcı forumumuzdaki sık sorulan soruların yer aldığı bu Civic Info API SSS sayfasına göz atabilirsiniz. Ayrıca, seçim sırasında seçmen bilgilerini aradığınıza dair örnekleri aşağıda bulabilirsiniz.
Uygulamanızı Google'a tanıtma
Uygulamanızın, Google Civic Information API'ye her istek gönderdiğinde her isteğe bir API anahtarı ekleyerek kendini tanımlaması gerekir.
API anahtarı edinme ve kullanma
API anahtarı edinmek için:
- API Konsolu'nda Kimlik bilgileri sayfasını açın.
-
Bu API iki tür kimlik bilgisini destekler.
Projeniz için uygun kimlik bilgilerini oluşturun:
-
OAuth 2.0: Uygulamanız gizli kullanıcı verileri istediğinde istekle birlikte bir OAuth 2.0 jetonu göndermelidir. Uygulamanız, jeton almak için önce bir istemci kimliği ve muhtemelen bir istemci gizli anahtarı gönderir. Web uygulamaları, hizmet hesapları veya yüklü uygulamalar için OAuth 2.0 kimlik bilgileri oluşturabilirsiniz.
Not: Bu API'de OAuth 2.0 yetkilendirmesi gerektiren herhangi bir yöntem olmadığından, yalnızca aşağıda açıklanan API anahtarlarını almanız gerekebilir. Ancak uygulamanız, kullanıcı yetkilendirmesi gerektiren başka API'ler çağırıyorsa OAuth 2.0 kimlik bilgilerine yine de ihtiyacınız vardır.
Daha fazla bilgi için OAuth 2.0 belgelerine göz atın.
-
API anahtarları: OAuth 2.0 jetonu sağlamayan bir istek, API anahtarı göndermelidir. Anahtar, projenizi tanımlar ve API erişimi, kota ve raporlar sağlar.
API, API anahtarlarında çeşitli kısıtlama türlerini destekler. İhtiyacınız olan API anahtarı yoksa Kimlik bilgileri oluştur > API anahtarı'nı tıklayarak Console'da API anahtarı oluşturun. Anahtarı kısıtla'yı tıklayıp Kısıtlamalar'dan birini seçerek anahtarı üretimde kullanmadan önce kısıtlayabilirsiniz.
-
API anahtarlarınızın güvenliğini sağlamak için API anahtarlarını güvenli bir şekilde kullanmayla ilgili en iyi uygulamaları uygulayın.
API anahtarınız olduktan sonra uygulamanız, key=yourAPIKey sorgu parametresini tüm istek URL'lerine ekleyebilir.
API anahtarı, URL'lere yerleştirmek için güvenlidir; herhangi bir kodlama yapmanız gerekmez.
API anahtarı kısıtlamaları
API anahtarınız varsayılan olarak kısıtlanmamıştır. Bu anahtar, okunabilir (ör. bir tarayıcıya yerleştirilmişse) veya anahtarın yerleştirildiği cihaza erişilebilirse güvenli değildir. Yetkisiz kullanımı engellemek için bu API anahtarına kısıtlama uygulamanızı öneririz.
Kısıtlama eklemek için API anahtarı oluşturuldu iletişim kutusunda Anahtarı kısıtla'yı tıklayın. API anahtarı yapılandırma paneli görünür:
Seçtiğiniz kısıtlama türü, uygulama ihtiyaçlarınıza bağlıdır:
- Doğrudan API ile etkileşime geçen (yani herhangi bir arka uç veya orta katman üzerinden değil) web uygulamaları bir HTTP yönlendirenleri kısıtlaması eklemelidir. Ancak bu tür uygulamaların API anahtarlarını herkese açık olarak göstereceğini unutmayın. Bunun yerine bir hizmet hesabı kimlik doğrulama şeması kullanmayı tercih edin.
- Hizmet hesaplarını başka bir şekilde destekleyemeyen arka uç uygulamaları (örneğin, istemci kitaplığında desteklenen bir dili olmayan yerleşik cihazlar), farklı IP adreslerindeki istemcilerden gelen kullanıma karşı koruma sağlamak için bir IP adresi kısıtlaması eklemelidir.
- Android uygulamaları, Android uygulamaları kısıtlaması eklemeli, paketinizin adını ve SHA-1 imza sertifikası parmak izini eklemelidir.
- iOS uygulamaları, API çağrılarını bu iOS paketleriyle kısıtlamak için bir iOS uygulamaları kısıtlaması ve iOS paketi tanımlayıcıları eklemelidir.
Test için hiç kısıtlama koymak istemeyebilirsiniz. Ancak uygulamanızı üretime dağıttıktan sonra bu anahtara kısıtlama eklemeniz veya anahtarı silmeniz önerilir.
electionQuery örneği
Aşağıda, geçerli seçim kimliklerinin listesini almak için electionQuery API'yi çağırıp ardından seçtiğiniz bir seçimle ilgili bilgileri almak için seçmen kaydındaki adresle voterInfoQuery API 'yi kullanan bir örnek (API sürümü "v2" kullanılarak) verilmiştir.
Geçerli seçim kimliklerinin listesini almak için electionQuery'yi kullanın:
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
electionQuery Yanıtı:
{
"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"
}
]
}curl kullanarak voterInfoQuery
2000 VIP test seçim kimliği ve 340 Main St, Venice, CA 90291 (test) adresindeki seçmen için voterInfoQuery isteği göndermek üzere curl kullanın.
voterInfoQuery yanıtını inceleyebilirsiniz.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
JavaScript için Google API İstemci Kitaplığı'nı kullanarak voterInfoQuery
Bu örnek, önceki curl örneğiyle aynı voterInfoQuery'yi gönderir ancak JavaScript istemci kitaplığını kullanır. voterInfoQuery yanıtı, curl örnek yanıtıyla aynıdır.
<!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 yanıtı
{ "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 } ] } } ] }