دستورالعمل های داده های توسعه دهنده

اطلاعات رأی‌گیری

رابط برنامه‌نویسی کاربردی اطلاعات مدنی گوگل (Google Civic Information API) اطلاعات مدنی مانند محل رأی‌گیری، محل رأی‌گیری زودهنگام، اطلاعات تماس مقامات انتخابات محلی و اطلاعات برگه رأی را برای انتخابات پشتیبانی‌شده توسط پروژه اطلاعات رأی‌گیری به کاربران برمی‌گرداند.

دسترسی به داده‌ها

دستورالعمل‌های توسعه‌دهنده

ما از همه توسعه‌دهندگان می‌خواهیم که دستورالعمل‌های زیر را رعایت کنند:

  • به شرایط خدمات APIها پایبند باشید.
  • با استفاده از API، توسعه‌دهندگان موافقت می‌کنند که در صورت وجود هرگونه هدر کنترل حافظه پنهان، از آن پیروی کنند. در صورت عدم وجود هدرهای کنترل حافظه پنهان، توسعه‌دهندگان موافقت می‌کنند که اطلاعات مکان‌های رأی‌گیری و مسابقه را بیش از ۲۴ ساعت و اطلاعات صاحبان دفاتر و مناطق را بیش از ۳۰ روز در حافظه پنهان ذخیره نکنند.
  • توسعه‌دهندگانی که از API استفاده می‌کنند باید تمام تلاش خود را بکنند تا اطمینان حاصل کنند که همه کاربران تجربه یکسانی را تجربه می‌کنند. ما اجازه طفره رفتن، تست A/B یا آزمایش‌های مشابه را نمی‌دهیم.

  • اگر برای فعال کردن مورد استفاده خود به سهمیه اضافی نیاز دارید، می‌توانید در کنسول توسعه‌دهندگان خود درخواست افزایش سهمیه به ازای هر پروژه را بدهید. تأمین سهمیه اضافی محدود است و تابع حداکثر سهمیه مجاز است.

    توجه: فرآیند تأیید ۱ تا ۲ ماه طول می‌کشد. درخواست‌های افزایش سهمیه خود را بر این اساس برنامه‌ریزی کنید. برای آمادگی جهت افزایش سهمیه انتخابات ریاست جمهوری ۲۰۲۴، درخواست‌های سهمیه خود را تا ماه اوت ارسال کنید.

  • سهمیه اضافی برای API اطلاعات مدنی فقط برای پشتیبانی از موارد استفاده کاربر در نظر گرفته شده است. درخواست‌های افزایش سهمیه برای موارد استفاده دیگر اعطا نمی‌شود.

دستورالعمل‌های تکمیلی داده‌ها

کار با این داده‌ها به طور خاص دشوار است. لطفاً نکات زیر را در نظر داشته باشید.

  • مقامات انتخاباتی اغلب در چند هفته آخر و حتی چند روز آخر قبل از انتخابات، این داده‌ها را اصلاح می‌کنند. ایده خوبی است که به کاربران هشدار داده شود که قبل از رأی دادن، دوباره آنها را بررسی کنند.
  • بیشتر فیدهای رسمی شامل بخش‌های خیابانی هستند، به این معنی که مقامات انتخاباتی طیف وسیعی از آدرس‌ها را به حوزه‌های انتخابیه و مکان‌های رأی‌گیری مرتبط می‌کنند. این محدوده‌ها ممکن است هیچ رأی‌دهنده‌ای در آن آدرس ثبت‌نام نکرده باشند یا نداشته باشند. در نتیجه، برای ایالت‌هایی که فیدهای رسمی را از طریق پروژه اطلاعات رأی‌گیری ارائه می‌دهند، آدرسی که در آن هیچ رأی‌دهنده ثبت‌نام‌شده‌ای وجود ندارد، ممکن است موفقیت‌آمیز باشد.
  • برای ایالت‌هایی که فید رسمی ارائه نمی‌دهند، فقط آدرس‌هایی که در آنها رأی‌دهنده ثبت‌نام‌شده وجود دارد، با موفقیت اعلام خواهند شد.
  • در برخی موارد، ما برای اطلاعات یکسان، چندین منبع داریم. ما باکیفیت‌ترین اطلاعات موجود برای اطلاعات تماس مقامات انتخابات محلی و اطلاعات برگه‌های رأی را ارائه می‌دهیم. هیچ راهی برای لغو این رفتار وجود ندارد، مگر اینکه منابع غیررسمی را از طریق پارامتر officialSourcesOnly حذف کنیم. برای اطلاعات مربوط به محل رأی‌گیری، ما همیشه منابع داده رسمی را نسبت به سایر منابع در اولویت قرار می‌دهیم.
  • اگر مشکلاتی در کیفیت داده‌ها پیدا کنیم، ممکن است تا زمان حل مشکل، هیچ داده‌ای برای یک حوزه انتخاباتی خاص ارسال نکنیم.
  • اگر ما اطلاعاتی در مورد یک آدرس نداریم، لزوماً به این معنی نیست که هیچ کس برای رأی دادن در آنجا ثبت نام نکرده است. برنامه ها باید کاربران را برای کسب اطلاعات کامل به مقامات انتخاباتی محلی خود هدایت کنند.
  • انتخابات پس از روز انتخابات به طور خودکار منقضی می‌شوند. پس از آن تاریخ، هیچ داده‌ای برای انتخابات بازگردانده نخواهد شد.

انتساب

انتساب به API اطلاعات مدنی اختیاری است. اگر توسعه‌دهنده‌ای تصمیم به انتساب به API اطلاعات مدنی و پیوند دادن کاربران به اطلاعات بیشتر در API اطلاعات مدنی بگیرد، ما از توسعه‌دهندگان می‌خواهیم که از یکی از گزینه‌های زبان انتساب و صفحه وب لینک‌شده در زیر استفاده کنند:

  • «ارائه شده توسط رابط برنامه‌نویسی کاربردی اطلاعات مدنی»
  • «اطلاعات رأی‌گیری با پشتیبانی رابط برنامه‌نویسی کاربردی اطلاعات مدنی»
  • «اطلاعات رأی‌گیری با پشتیبانی رابط برنامه‌نویسی کاربردی اطلاعات مدنی»
  • «بیشتر بدانید»

کدهای وضعیت

فراخوانی‌های voterInfoQuery شامل یک فیلد status است که هنگام پذیرش آدرس، روی success تنظیم می‌شود. در موارد دیگر، یک کد خطا برگردانده می‌شود. توضیحات رایج برای کدهای خطا در زیر آمده است. توجه داشته باشید که حتی در صورت وجود کد خطا، ممکن است اطلاعات برگردانده شود.

وضعیت توضیح
success آدرس درخواستی توسط API به عنوان یک آدرس معتبر شناخته می‌شود.
noStreetSegmentFound API در حال حاضر هیچ اطلاعاتی در مورد اینکه این آدرس متعلق به کدام حوزه انتخابیه و/یا منطقه انتخاباتی است، ندارد. ممکن است ما هنوز در حال تهیه/پردازش داده‌های جدید باشیم، یا اینکه هیچ رأی‌دهنده‌ای برای رأی دادن در این آدرس ثبت‌نام نکرده باشد.
addressUnparseable آدرس درخواستی به درستی قالب‌بندی نشده است یا نمی‌تواند کد جغرافیایی داشته باشد (یعنی API نقشه‌های گوگل چیزی در مورد این آدرس نمی‌داند).
noAddressParameter هیچ آدرسی ارائه نشده بود.
multipleStreetSegmentsFound این API نمی‌تواند اطلاعات مربوط به آدرس مشخص شده را پیدا کند، اما اطلاعاتی در مورد آدرس‌های نزدیک دارد. کاربر باید برای اطلاعات بیشتر با مسئول انتخابات خود تماس بگیرد.
electionOver انتخابات درخواستی به پایان رسید. نتایج API برای انتخابات دیگر در دسترس نیست. برای یافتن شناسه انتخابات پیش رو، یک ElectionQuery ایجاد کنید.
electionUnknown شناسه انتخاباتی درخواستی نامعتبر است. برای یافتن شناسه معتبر، یک ElectionQuery ایجاد کنید.
internalLookupFailure خطای نامشخصی در پردازش درخواست رخ داده است.