يوضّح هذا المستند المعلومات التي تحتاج إلى معرفتها لاستخدام Google Civic Information API. يمكنك الاطّلاع على الأسئلة الشائعة حول Civic Info API التي تتضمّن بعض المعلومات الأساسية عن واجهة برمجة التطبيقات بالإضافة إلى الأسئلة الشائعة من منتدى المستخدمين. بالإضافة إلى ذلك، يمكنك الاطّلاع أدناه على أمثلة للبحث عن معلومات الناخبين أثناء الانتخابات.
تحديد تطبيقك لمحرك بحث Google
يجب أن يعرّف تطبيقك نفسه في كل مرة يرسل فيها طلبًا إلى Google Civic Information API، وذلك من خلال تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب.
الحصول على مفتاح واجهة برمجة التطبيقات واستخدامه
للحصول على مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:
- افتح صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات.
-
تتيح واجهة برمجة التطبيقات هذه نوعَين من بيانات الاعتماد.
أنشئ بيانات الاعتماد المناسبة لمشروعك:
-
بروتوكول OAuth 2.0: عندما يطلب تطبيقك بيانات مستخدمين خاصة، يجب أن يرسل رمزًا مميزًا لبروتوكول OAuth 2.0 مع الطلب. يُرسِل تطبيقك أولاً معرّف عميل، وربما سر عميل، للحصول على رمز مميّز. يمكنك إنشاء بيانات اعتماد OAuth 2.0 لتطبيقات الويب أو حسابات الخدمة أو التطبيقات المثبَّتة.
ملاحظة: بما أنّ واجهة برمجة التطبيقات هذه لا تتضمّن أي طرق تتطلّب تفويض OAuth 2.0، قد تحتاج فقط إلى الحصول على مفاتيح واجهة برمجة التطبيقات الموضّحة أدناه. ومع ذلك، إذا كان تطبيقك يستدعي واجهات برمجة تطبيقات أخرى تتطلّب تفويض المستخدم، سيظلّ عليك الحصول على بيانات اعتماد OAuth 2.0.
لمزيد من المعلومات، يُرجى الاطّلاع على مستندات OAuth 2.0.
-
مفاتيح واجهة برمجة التطبيقات: يجب أن يرسل الطلب الذي لا يقدّم رمزًا مميزًا لبروتوكول OAuth 2.0 مفتاح واجهة برمجة التطبيقات. ويحدِّد المفتاح مشروعك ويمنح إذن الوصول إلى واجهة برمجة التطبيقات والحصة والتقارير.
تتيح واجهة برمجة التطبيقات العديد من أنواع القيود المفروضة على مفاتيح واجهة برمجة التطبيقات. إذا لم يكن مفتاح واجهة برمجة التطبيقات الذي تحتاجه متوفّرًا، يمكنك إنشاء مفتاح واجهة برمجة التطبيقات في وحدة التحكّم من خلال النقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات. يمكنك فرض قيود على المفتاح قبل استخدامه في مرحلة الإنتاج من خلال النقر على فرض قيود على المفتاح واختيار أحد القيود.
-
للحفاظ على أمان مفاتيح واجهة برمجة التطبيقات، اتّبِع أفضل الممارسات المتعلقة باستخدام مفاتيح واجهة برمجة التطبيقات بأمان.
بعد الحصول على مفتاح واجهة برمجة التطبيقات، يمكن لتطبيقك إلحاق مَعلمة طلب البحث
key=yourAPIKey بجميع عناوين URL للطلبات.
مفتاح واجهة برمجة التطبيقات آمن لتضمينه في عناوين URL، ولا يحتاج إلى أي ترميز.
القيود المفروضة على مفاتيح واجهة برمجة التطبيقات
يكون مفتاح واجهة برمجة التطبيقات غير محظور تلقائيًا، ما يشكّل خطرًا إذا كان بإمكان أي مستخدم قراءة هذا المفتاح (إذا تم وضعه في متصفّح مثلاً) أو الوصول إلى الجهاز الذي تم وضع المفتاح عليه. ننصحك بفرض قيد على مفتاح واجهة برمجة التطبيقات هذا لمنع الاستخدام غير المصرّح به.
لإضافة قيد، انقر على تقييد المفتاح ضمن مربّع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه. ستظهر لوحة ضبط مفتاح واجهة برمجة التطبيقات:
يعتمد نوع القيود التي تختارها على احتياجات تطبيقك:
- يجب أن تضيف تطبيقات الويب التي تتفاعل مباشرةً مع واجهة برمجة التطبيقات (أي ليس من خلال أي نظام أساسي أو برنامج وسيط) قيدًا على مُحيلي HTTP. يُرجى العِلم أنّ هذه التطبيقات ستُعرِض مفتاح واجهة برمجة التطبيقات بشكل علني، لذلك ننصحك باستخدام مخطّط مصادقة حساب الخدمة بدلاً من ذلك.
- بالنسبة إلى تطبيقات الخلفية التي لا يمكنها استخدام حسابات الخدمة (مثل الأجهزة المضمّنة التي لا تتضمّن لغة متوافقة في مكتبة العميل)، يجب أن تضيف قيدًا على عناوين IP للحماية من الاستخدام من العملاء على عناوين IP مختلفة.
- يجب أن تضيف تطبيقات Android قيدًا على تطبيقات Android وأن تضيف اسم الحزمة والمرجع البصمي لشهادة التوقيع SHA-1.
- على تطبيقات iOS إضافة قيد تطبيقات iOS وإضافة أي معرّفات حِزم iOS لتقييد طلبات البيانات من واجهة برمجة التطبيقات على حِزم iOS هذه.
في ما يتعلّق بالاختبار، قد لا تريد فرض أي قيود على الإطلاق. ومع ذلك، ننصحك بإضافة قيد إلى هذا المفتاح أو حذفه بعد نشر تطبيقك في قناة الإصدار العلني.
مثال على electionQuery
في ما يلي مثال (باستخدام الإصدار 2 من واجهة برمجة التطبيقات) على طلب واجهة برمجة التطبيقات electionQuery للحصول على قائمة بأرقام تعريف الانتخابات الصالحة، ثم استخدام واجهة برمجة التطبيقات voterInfoQuery مع عنوان الناخب المسجّل للحصول على معلومات عن انتخابات محدّدة.
استخدِم electionQuery للحصول على قائمة بمعرّفات الانتخابات الصالحة:
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"
}
]
}voterInfoQuery باستخدام curl
استخدِم curl لإرسال طلب voterInfoQuery
للحصول على الرقم التعريفي للانتخابات التجريبية لكبار الشخصيات 2000 والمواطن المقيم في العنوان (التجريبي) 340 Main St, Venice, CA 90291.
يمكنك الرجوع إلى استجابة voterInfoQuery.
curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"
voterInfoQuery باستخدام مكتبة برامج Google API للغة JavaScript
يُصدر هذا المثال طلب voterInfoQuery نفسه المستخدَم في مثال curl السابق، ولكنه يستخدِم مكتبة 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 } ] } } ] }