با استفاده از API

این سند آنچه را که برای استفاده از Google Civic Information API باید بدانید را توضیح می دهد. می‌توانید به این سؤالات متداول Civic Info API نگاهی بیندازید که اطلاعات اولیه در مورد API و همچنین سؤالات متداول از انجمن کاربر ما دارد. علاوه بر این، می‌توانید نمونه‌هایی را در زیر برای جستجوی اطلاعات رأی‌دهندگان در طول انتخابات مشاهده کنید.

شناسایی اپلیکیشن شما در گوگل

برنامه شما باید هر بار که درخواستی به Google Civic Information API ارسال می‌کند، خود را با قرار دادن یک کلید API با هر درخواست شناسایی کند.

به دست آوردن و استفاده از یک کلید API

برای به دست آوردن یک کلید API:

1. صفحه Credentials را در کنسول API باز کنید.
2. این API از دو نوع اعتبارنامه پشتیبانی می کند. هر اعتباری را که برای پروژه شما مناسب است ایجاد کنید:

   • OAuth 2.0: هر زمان که برنامه شما اطلاعات کاربر خصوصی را درخواست می کند، باید یک توکن OAuth 2.0 را همراه با درخواست ارسال کند. برنامه شما ابتدا یک شناسه مشتری و احتمالاً یک رمز سرویس گیرنده را برای دریافت رمز ارسال می کند. می توانید اعتبارنامه OAuth 2.0 را برای برنامه های کاربردی وب، حساب های خدماتی یا برنامه های نصب شده ایجاد کنید.

     توجه: از آنجایی که این API هیچ روشی ندارد که به مجوز OAuth 2.0 نیاز داشته باشد، ممکن است فقط نیاز به دریافت کلیدهای API داشته باشید که در زیر توضیح داده شده است. با این حال، اگر برنامه شما API های دیگری را که نیاز به مجوز کاربر دارند فراخوانی می کند، همچنان به اعتبارنامه OAuth 2.0 نیاز دارید.

     برای اطلاعات بیشتر، به مستندات OAuth 2.0 مراجعه کنید.

   • کلیدهای API: درخواستی که توکن OAuth 2.0 ارائه نمی کند باید یک کلید API ارسال کند. کلید پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را فراهم می کند.

     API از چندین نوع محدودیت در کلیدهای API پشتیبانی می کند. اگر کلید API مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

برای ایمن نگه داشتن کلیدهای API خود، بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

محدودیت های کلید API

کلید API شما به طور پیش‌فرض نامحدود است، که اگر کسی بتواند این کلید را بخواند (مثلاً اگر در مرورگر قرار داده شده باشد) یا به دستگاهی که کلید روی آن قرار داده شده است دسترسی پیدا کند، ناامن است. توصیه می کنیم برای جلوگیری از استفاده غیرمجاز، محدودیتی روی این کلید API اعمال کنید.

برای افزودن محدودیت، روی Restrict key در کادر محاوره ای ایجاد شده با API کلیک کنید. پانل پیکربندی کلید API ظاهر می شود:

نوع محدودیتی که انتخاب می کنید به نیازهای برنامه شما بستگی دارد:

• برنامه های کاربردی وب که مستقیماً با API در تعامل هستند (یعنی نه از طریق هیچ باطن یا میان افزاری) باید یک محدودیت ارجاع دهنده HTTP اضافه کنند. با این حال، توجه داشته باشید که چنین برنامه‌هایی کلید API خود را به صورت عمومی نشان می‌دهند. ترجیح می دهند به جای آن از طرح تأیید حساب سرویس استفاده کنند.
• برنامه‌های کاربردی که نمی‌توانند از حساب‌های سرویس پشتیبانی کنند (مثلاً دستگاه‌های تعبیه‌شده که زبان پشتیبانی‌شده در کتابخانه سرویس گیرنده ندارند) باید یک محدودیت آدرس IP اضافه کنند تا از استفاده مشتریان در آدرس‌های IP مختلف محافظت کنند.
• برنامه‌های Android باید یک محدودیت برنامه‌های Android اضافه کنند و نام بسته و اثر انگشت گواهی امضای SHA-1 را اضافه کنند.
• برنامه‌های iOS باید یک محدودیت برنامه‌های iOS اضافه کنند و هر شناسه بسته iOS را اضافه کنند تا تماس‌های API را به این بسته‌های iOS محدود کنند.

برای آزمایش، ممکن است اصلاً نخواهید محدودیتی ایجاد کنید. با این حال، توصیه می شود که یا محدودیتی به این کلید اضافه کنید یا پس از استقرار برنامه خود در تولید، آن را حذف کنید.

نمونه پرس و جو انتخاباتی

در اینجا یک مثال (با استفاده از نسخه API 'v2') فراخوانی انتخاب‌کننده API برای به دست آوردن فهرستی از شناسه‌های انتخاباتی معتبر، سپس استفاده از voterInfoQuery API با آدرس ثبت‌شده یک رأی‌دهنده برای به دست آوردن اطلاعات برای یک انتخابات انتخابی است.

برای دریافت فهرستی از شناسه‌های معتبر انتخاباتی از ElectionQuery استفاده کنید:

  https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
  

پاسخ به سوالات انتخاباتی:

{
 "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 برای شناسه انتخاباتی آزمون VIP 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 Client Library برای جاوا اسکریپت

این مثال همان voterInfoQuery را مانند نمونه curl قبلی صادر می کند، اما از کتابخانه مشتری جاوا اسکریپت استفاده می کند. پاسخ 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
          }
        ]
      }
    }
  ]
}

،

این سند آنچه را که برای استفاده از Google Civic Information API باید بدانید را توضیح می دهد. می‌توانید به این سؤالات متداول Civic Info API نگاهی بیندازید که اطلاعات اولیه در مورد API و همچنین سؤالات متداول از انجمن کاربر ما دارد. علاوه بر این، می‌توانید نمونه‌هایی را در زیر برای جستجوی اطلاعات رأی‌دهندگان در طول انتخابات مشاهده کنید.

شناسایی اپلیکیشن شما در گوگل

برنامه شما باید هر بار که درخواستی به Google Civic Information API ارسال می‌کند، خود را با قرار دادن یک کلید API با هر درخواست شناسایی کند.

به دست آوردن و استفاده از یک کلید API

برای به دست آوردن یک کلید API:

1. صفحه Credentials را در کنسول API باز کنید.
2. این API از دو نوع اعتبارنامه پشتیبانی می کند. هر اعتباری را که برای پروژه شما مناسب است ایجاد کنید:

   • OAuth 2.0: هر زمان که برنامه شما اطلاعات کاربر خصوصی را درخواست می کند، باید یک توکن OAuth 2.0 را همراه با درخواست ارسال کند. برنامه شما ابتدا یک شناسه مشتری و احتمالاً یک رمز سرویس گیرنده را برای دریافت رمز ارسال می کند. می توانید اعتبارنامه OAuth 2.0 را برای برنامه های کاربردی وب، حساب های خدماتی یا برنامه های نصب شده ایجاد کنید.

     توجه: از آنجایی که این API هیچ روشی ندارد که به مجوز OAuth 2.0 نیاز داشته باشد، ممکن است فقط نیاز به دریافت کلیدهای API داشته باشید که در زیر توضیح داده شده است. با این حال، اگر برنامه شما API های دیگری را که نیاز به مجوز کاربر دارند فراخوانی می کند، همچنان به اعتبارنامه OAuth 2.0 نیاز دارید.

     برای اطلاعات بیشتر، به مستندات OAuth 2.0 مراجعه کنید.

   • کلیدهای API: درخواستی که توکن OAuth 2.0 ارائه نمی کند باید یک کلید API ارسال کند. کلید پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را فراهم می کند.

     API از چندین نوع محدودیت در کلیدهای API پشتیبانی می کند. اگر کلید API مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

برای ایمن نگه داشتن کلیدهای API خود، بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

محدودیت های کلید API

کلید API شما به طور پیش‌فرض نامحدود است، که اگر کسی بتواند این کلید را بخواند (مثلاً اگر در مرورگر قرار داده شده باشد) یا به دستگاهی که کلید روی آن قرار داده شده است دسترسی پیدا کند، ناامن است. توصیه می کنیم برای جلوگیری از استفاده غیرمجاز، محدودیتی روی این کلید API اعمال کنید.

برای افزودن محدودیت، روی Restrict key در کادر محاوره ای ایجاد شده با API کلیک کنید. پانل پیکربندی کلید API ظاهر می شود:

نوع محدودیتی که انتخاب می کنید به نیازهای برنامه شما بستگی دارد:

• برنامه های کاربردی وب که مستقیماً با API در تعامل هستند (یعنی نه از طریق هیچ باطن یا میان افزاری) باید یک محدودیت ارجاع دهنده HTTP اضافه کنند. با این حال، توجه داشته باشید که چنین برنامه‌هایی کلید API خود را به صورت عمومی نشان می‌دهند. ترجیح می دهند به جای آن از طرح تأیید حساب سرویس استفاده کنند.
• برنامه‌های کاربردی که نمی‌توانند از حساب‌های سرویس پشتیبانی کنند (مثلاً دستگاه‌های تعبیه‌شده که زبان پشتیبانی‌شده در کتابخانه سرویس گیرنده ندارند) باید یک محدودیت آدرس IP اضافه کنند تا از استفاده مشتریان در آدرس‌های IP مختلف محافظت کنند.
• برنامه‌های Android باید یک محدودیت برنامه‌های Android اضافه کنند و نام بسته و اثر انگشت گواهی امضای SHA-1 را اضافه کنند.
• برنامه‌های iOS باید یک محدودیت برنامه‌های iOS اضافه کنند و هر شناسه بسته iOS را اضافه کنند تا تماس‌های API را به این بسته‌های iOS محدود کنند.

برای آزمایش، ممکن است اصلاً نخواهید محدودیتی ایجاد کنید. با این حال، توصیه می شود که یا محدودیتی به این کلید اضافه کنید یا پس از استقرار برنامه خود در تولید، آن را حذف کنید.

نمونه پرس و جو انتخاباتی

در اینجا یک مثال (با استفاده از نسخه API 'v2') فراخوانی انتخاب‌کننده API برای به دست آوردن فهرستی از شناسه‌های انتخاباتی معتبر، سپس استفاده از voterInfoQuery API با آدرس ثبت‌شده یک رأی‌دهنده برای به دست آوردن اطلاعات برای یک انتخابات انتخابی است.

برای دریافت فهرستی از شناسه‌های معتبر انتخاباتی از ElectionQuery استفاده کنید:

  https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
  

پاسخ به سوالات انتخاباتی:

{
 "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 برای شناسه انتخاباتی آزمون VIP 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 Client Library برای جاوا اسکریپت

این مثال همان voterInfoQuery را مانند نمونه curl قبلی صادر می کند، اما از کتابخانه مشتری جاوا اسکریپت استفاده می کند. پاسخ 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
          }
        ]
      }
    }
  ]
}

،

این سند آنچه را که برای استفاده از Google Civic Information API باید بدانید را توضیح می دهد. می‌توانید به این سؤالات متداول Civic Info API نگاهی بیندازید که اطلاعات اولیه در مورد API و همچنین سؤالات متداول از انجمن کاربر ما دارد. علاوه بر این، می‌توانید نمونه‌هایی را در زیر برای جستجوی اطلاعات رأی‌دهندگان در طول انتخابات مشاهده کنید.

شناسایی اپلیکیشن شما در گوگل

برنامه شما باید هر بار که درخواستی به Google Civic Information API ارسال می‌کند، خود را با قرار دادن یک کلید API با هر درخواست شناسایی کند.

به دست آوردن و استفاده از یک کلید API

برای به دست آوردن یک کلید API:

1. صفحه Credentials را در کنسول API باز کنید.
2. این API از دو نوع اعتبارنامه پشتیبانی می کند. هر اعتباری را که برای پروژه شما مناسب است ایجاد کنید:

   • OAuth 2.0: هر زمان که برنامه شما اطلاعات کاربر خصوصی را درخواست می کند، باید یک توکن OAuth 2.0 را همراه با درخواست ارسال کند. برنامه شما ابتدا یک شناسه مشتری و احتمالاً یک رمز سرویس گیرنده را برای دریافت رمز ارسال می کند. می توانید اعتبارنامه OAuth 2.0 را برای برنامه های کاربردی وب، حساب های خدماتی یا برنامه های نصب شده ایجاد کنید.

     توجه: از آنجایی که این API هیچ روشی ندارد که به مجوز OAuth 2.0 نیاز داشته باشد، ممکن است فقط نیاز به دریافت کلیدهای API داشته باشید که در زیر توضیح داده شده است. با این حال، اگر برنامه شما API های دیگری را که نیاز به مجوز کاربر دارند فراخوانی می کند، همچنان به اعتبارنامه OAuth 2.0 نیاز دارید.

     برای اطلاعات بیشتر، به مستندات OAuth 2.0 مراجعه کنید.

   • کلیدهای API: درخواستی که توکن OAuth 2.0 ارائه نمی کند باید یک کلید API ارسال کند. کلید پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را فراهم می کند.

     API از چندین نوع محدودیت در کلیدهای API پشتیبانی می کند. اگر کلید API مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

برای ایمن نگه داشتن کلیدهای API خود، بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

محدودیت های کلید API

کلید API شما به طور پیش‌فرض نامحدود است، که اگر کسی بتواند این کلید را بخواند (مثلاً اگر در مرورگر قرار داده شده باشد) یا به دستگاهی که کلید روی آن قرار داده شده است دسترسی پیدا کند، ناامن است. توصیه می کنیم برای جلوگیری از استفاده غیرمجاز، محدودیتی روی این کلید API اعمال کنید.

برای افزودن محدودیت، روی Restrict key در کادر محاوره ای ایجاد شده با API کلیک کنید. پانل پیکربندی کلید API ظاهر می شود:

نوع محدودیتی که انتخاب می کنید به نیازهای برنامه شما بستگی دارد:

• برنامه های کاربردی وب که مستقیماً با API در تعامل هستند (یعنی نه از طریق هیچ باطن یا میان افزاری) باید یک محدودیت ارجاع دهنده HTTP اضافه کنند. با این حال، توجه داشته باشید که چنین برنامه‌هایی کلید API خود را به صورت عمومی نشان می‌دهند. ترجیح می دهند به جای آن از طرح تأیید حساب سرویس استفاده کنند.
• برنامه‌های کاربردی که نمی‌توانند از حساب‌های سرویس پشتیبانی کنند (مثلاً دستگاه‌های تعبیه‌شده که زبان پشتیبانی‌شده در کتابخانه سرویس گیرنده ندارند) باید یک محدودیت آدرس IP اضافه کنند تا از استفاده مشتریان در آدرس‌های IP مختلف محافظت کنند.
• برنامه‌های Android باید یک محدودیت برنامه‌های Android اضافه کنند و نام بسته و اثر انگشت گواهی امضای SHA-1 را اضافه کنند.
• برنامه‌های iOS باید یک محدودیت برنامه‌های iOS اضافه کنند و هر شناسه بسته iOS را اضافه کنند تا تماس‌های API را به این بسته‌های iOS محدود کنند.

برای آزمایش، ممکن است اصلاً نخواهید محدودیتی ایجاد کنید. با این حال، توصیه می شود که یا محدودیتی به این کلید اضافه کنید یا پس از استقرار برنامه خود در تولید، آن را حذف کنید.

نمونه پرس و جو انتخاباتی

در اینجا یک مثال (با استفاده از نسخه API 'v2') فراخوانی انتخاب‌کننده API برای به دست آوردن فهرستی از شناسه‌های انتخاباتی معتبر، سپس استفاده از voterInfoQuery API با آدرس ثبت‌شده یک رأی‌دهنده برای به دست آوردن اطلاعات برای یک انتخابات انتخابی است.

برای دریافت فهرستی از شناسه‌های معتبر انتخاباتی از ElectionQuery استفاده کنید:

  https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
  

پاسخ به سوالات انتخاباتی:

{
 "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 برای شناسه انتخاباتی آزمون VIP 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 Client Library برای جاوا اسکریپت

این مثال همان voterInfoQuery را مانند نمونه curl قبلی صادر می کند، اما از کتابخانه مشتری جاوا اسکریپت استفاده می کند. پاسخ 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
          }
        ]
      }
    }
  ]
}

،

این سند آنچه را که برای استفاده از Google Civic Information API باید بدانید را توضیح می دهد. می‌توانید به این سؤالات متداول Civic Info API نگاهی بیندازید که اطلاعات اولیه در مورد API و همچنین سؤالات متداول از انجمن کاربر ما دارد. علاوه بر این، می‌توانید نمونه‌هایی را در زیر برای جستجوی اطلاعات رأی‌دهندگان در طول انتخابات مشاهده کنید.

شناسایی اپلیکیشن شما در گوگل

برنامه شما باید هر بار که درخواستی به Google Civic Information API ارسال می‌کند، خود را با قرار دادن یک کلید API با هر درخواست شناسایی کند.

به دست آوردن و استفاده از یک کلید API

برای به دست آوردن یک کلید API:

1. صفحه Credentials را در کنسول API باز کنید.
2. این API از دو نوع اعتبارنامه پشتیبانی می کند. هر اعتباری را که برای پروژه شما مناسب است ایجاد کنید:

   • OAuth 2.0: هر زمان که برنامه شما اطلاعات کاربر خصوصی را درخواست می کند، باید یک توکن OAuth 2.0 را همراه با درخواست ارسال کند. برنامه شما ابتدا یک شناسه مشتری و احتمالاً یک رمز سرویس گیرنده را برای دریافت رمز ارسال می کند. می توانید اعتبارنامه OAuth 2.0 را برای برنامه های کاربردی وب، حساب های خدماتی یا برنامه های نصب شده ایجاد کنید.

     توجه: از آنجایی که این API هیچ روشی ندارد که به مجوز OAuth 2.0 نیاز داشته باشد، ممکن است فقط نیاز به دریافت کلیدهای API داشته باشید که در زیر توضیح داده شده است. با این حال، اگر برنامه شما API های دیگری را که نیاز به مجوز کاربر دارند فراخوانی می کند، همچنان به اعتبارنامه OAuth 2.0 نیاز دارید.

     برای اطلاعات بیشتر، به مستندات OAuth 2.0 مراجعه کنید.

   • کلیدهای API: درخواستی که توکن OAuth 2.0 ارائه نمی کند باید یک کلید API ارسال کند. کلید پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را فراهم می کند.

     API از چندین نوع محدودیت در کلیدهای API پشتیبانی می کند. اگر کلید API مورد نیاز شما از قبل وجود ندارد، با کلیک روی ایجاد اعتبار > کلید API، یک کلید API در کنسول ایجاد کنید. می‌توانید کلید را قبل از استفاده از آن در تولید با کلیک کردن روی Restrict key و انتخاب یکی از محدودیت‌ها محدود کنید.

برای ایمن نگه داشتن کلیدهای API خود، بهترین روش ها را برای استفاده ایمن از کلیدهای API دنبال کنید.

بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey به همه URL های درخواستی اضافه کند.

کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.

محدودیت های کلید API

کلید API شما به طور پیش‌فرض نامحدود است، که اگر کسی بتواند این کلید را بخواند (مثلاً اگر در مرورگر قرار داده شده باشد) یا به دستگاهی که کلید روی آن قرار داده شده است دسترسی پیدا کند، ناامن است. توصیه می کنیم برای جلوگیری از استفاده غیرمجاز، محدودیتی روی این کلید API اعمال کنید.

برای افزودن محدودیت، روی Restrict key در کادر محاوره ای ایجاد شده با API کلیک کنید. پانل پیکربندی کلید API ظاهر می شود:

نوع محدودیتی که انتخاب می کنید به نیازهای برنامه شما بستگی دارد:

• برنامه های کاربردی وب که مستقیماً با API در تعامل هستند (یعنی نه از طریق هیچ باطن یا میان افزاری) باید یک محدودیت ارجاع دهنده HTTP اضافه کنند. با این حال، توجه داشته باشید که چنین برنامه‌هایی کلید API خود را به صورت عمومی نشان می‌دهند. ترجیح می دهند به جای آن از طرح تأیید حساب سرویس استفاده کنند.
• برنامه‌های کاربردی که نمی‌توانند از حساب‌های سرویس پشتیبانی کنند (مثلاً دستگاه‌های تعبیه‌شده که زبان پشتیبانی‌شده در کتابخانه سرویس گیرنده ندارند) باید یک محدودیت آدرس IP اضافه کنند تا از استفاده مشتریان در آدرس‌های IP مختلف محافظت کنند.
• برنامه‌های Android باید یک محدودیت برنامه‌های Android اضافه کنند و نام بسته و اثر انگشت گواهی امضای SHA-1 را اضافه کنند.
• برنامه‌های iOS باید یک محدودیت برنامه‌های iOS اضافه کنند و هر شناسه بسته iOS را اضافه کنند تا تماس‌های API را به این بسته‌های iOS محدود کنند.

برای آزمایش، ممکن است اصلاً نخواهید محدودیتی ایجاد کنید. با این حال، توصیه می شود که یا محدودیتی به این کلید اضافه کنید یا پس از استقرار برنامه خود در تولید، آن را حذف کنید.

نمونه پرس و جو انتخاباتی

در اینجا یک مثال (با استفاده از نسخه API 'v2') فراخوانی انتخاب‌کننده API برای به دست آوردن فهرستی از شناسه‌های انتخاباتی معتبر، سپس استفاده از voterInfoQuery API با آدرس ثبت‌شده یک رأی‌دهنده برای به دست آوردن اطلاعات برای یک انتخابات انتخابی است.

برای دریافت فهرستی از شناسه‌های معتبر انتخاباتی از ElectionQuery استفاده کنید:

  https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>
  

پاسخ به سوالات انتخاباتی:

{
 "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 برای شناسه انتخاباتی آزمون VIP 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 Client Library برای جاوا اسکریپت

این مثال همان voterInfoQuery را مانند نمونه curl قبلی صادر می کند، اما از کتابخانه مشتری جاوا اسکریپت استفاده می کند. پاسخ 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
          }
        ]
      }
    }
  ]
}