このドキュメントでは、Google Civic Information API を使用する際に知っておくべきことについて説明します。Civic Info API に関するよくある質問をご覧ください。API に関する基本情報と、ユーザー フォーラムでのよくある質問が記載されています。また、選挙中に有権者情報を検索する例を以下に示します。
Google でアプリケーションを識別する
アプリケーションは、Google Civic Information API にリクエストを送信するたびに、各リクエストに API キーを含めて、自身を識別する必要があります。
API キーの取得と使用
API キーを取得するには:
- API コンソールで [認証情報] ページを開きます。
-
この API は 2 種類の認証情報をサポートします。プロジェクトに適したいずれかの認証情報を作成します。
-
OAuth 2.0: アプリケーションからユーザーの限定公開データをリクエストする場合は、リクエストとともに OAuth 2.0 トークンを送信する必要があります。アプリケーションは、トークンを取得するためにまずクライアント ID を送信します。場合によってはクライアント シークレットも送信します。ウェブ アプリケーション、サービス アカウント、インストールしたアプリケーションについて OAuth 2.0 認証情報を生成できます。
注: この API には OAuth 2.0 認証を必要とするメソッドがないため、API キーのみを取得する必要があります。API キーについては、後で説明します。ただし、ユーザー認証を必要とする他の API を アプリケーションで呼び出す場合は、OAuth 2.0 認証情報が必要となります。
詳細については、OAuth 2.0 ドキュメントをご覧ください。
-
API キー: OAuth 2.0 トークンが提供されないリクエストでは、API キーを送信する必要があります。 キーによりプロジェクトが識別され、API アクセス、割り当て、レポートが提供されます。
API は、いくつかのタイプの API キーをサポートします。必要とする API キーのタイプが存在しない場合は、[認証情報作成] > [API キー] をクリックして、コンソールで API キーを作成します。本番環境でそれを使用する前にキーを制限するには、[キーを制限] をクリックして、いずれかの制限を選択します。
-
API キーの安全性を保つには、API キーを安全に使用するためのおすすめの方法に従ってください。
API キーを作成したら、アプリケーションですべてのリクエスト URL の末尾にクエリ パラメータ key=yourAPIKey を追加できます。
API キーは、安全に URL に埋め込むことができます。エンコーディングの必要はありません。
API キーの制限
API キーはデフォルトで制限なしです。このキーを誰でも読み取ったり（ブラウザ内に配置されている場合など）、キーが配置されているデバイスにアクセスしたりできると、安全ではありません。不正使用を防ぐため、この API キーに制限を設定することをおすすめします。
制限を追加するには、[API キーを作成しました] ダイアログ ボックスで [鍵を制限] をクリックします。[API キー] 構成パネルが表示されます。
選択する制限のタイプはアプリケーションのニーズによって異なります。
- API と直接やり取りするウェブ アプリケーション（バックエンドやミドルウェアを介さない）には、HTTP リファラーの制限を追加する必要があります。ただし、このようなアプリケーションでは API キーが公開されるため、代わりにサービス アカウント認証スキームを使用することをおすすめします。
- サービス アカウントをサポートできないバックエンド アプリケーション（クライアント ライブラリでサポートされている言語がない組み込みデバイスなど）は、異なる IP アドレスのクライアントからの使用を防ぐために、IP アドレスの制限を追加する必要があります。
- Android アプリは、Android アプリの制限を追加し、パッケージ名と SHA-1 署名証明書フィンガープリントを追加する必要があります。
- iOS アプリは、iOS アプリの制限を追加し、iOS バンドル ID を追加して、これらの iOS バンドルへの API 呼び出しを制限する必要があります。
テストの場合は、制限を設定する必要はありません。ただし、アプリケーションを本番環境にデプロイしたら、このキーに制限を追加するか、削除することをおすすめします。
electionQuery の例
electionQuery API を呼び出して有効な選挙 ID のリストを取得し、voterInfoQuery API を使用して有権者の登録住所から選択した選挙の情報を取得する（API バージョン「v2」を使用）例を次に示します。
electionQuery を使用して、有効な選挙 ID のリストを取得します。
https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
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"
}
]
}curl を使用した voterInfoQuery
curl を使用して、VIP テスト選挙 ID 2000 と（テスト）住所 340 Main St, Venice, CA 90291 の有権者に関する voterInfoQuery リクエストを送信します。voterInfoQuery レスポンスを参照してください。
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
JavaScript の Google API クライアント ライブラリを使用した voterInfoQuery
この例では、前の curl の例と同じ voterInfoQuery を発行しますが、JavaScript クライアント ライブラリを使用します。voterInfoQuery レスポンスは、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>
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 } ] } } ] }