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

جغرافیای سیاسی و نمایندگان منتخب

Google Civic Information API اطلاعاتی درباره تقسیمات جغرافیایی سیاسی و نمایندگان منتخب برای آدرس های ایالات متحده از سطح فدرال تا محلی ارائه می دهد. در حال حاضر، پوشش 100 درصدی برای مناطق ایالتی، شهرستانی و کنگره داریم و هدف آن فراتر از 90 درصد پوشش برای مناطق قانونگذاری ایالتی است. سطوح پایین تر، مانند شوراهای شهر و شهرستان، بر اساس بهترین تلاش ارائه می شوند و در طول زمان بهبود خواهند یافت.

ما انتظار داریم که اطلاعات به روزی در مورد همه مقامات منتخب در سطوح فدرال، ایالتی و شهرستانی و مقامات شهری برای بزرگترین شهر در هر ایالت ایالات متحده و همچنین هر شهر با جمعیت بیش از 250000 نفر داشته باشیم. ما این داده‌ها را از منابع متعدد جمع‌آوری می‌کنیم و با بالاترین کیفیت اطلاعات موجود را ارائه می‌کنیم. اگر مشکلات کیفیت داده‌ها را کشف کنیم، ممکن است بازگرداندن داده‌ها را برای بخش‌های جغرافیایی خاص، دفاتر منتخب یا مقامات منتخب متوقف کنیم.

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

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

در دسترس بودن داده ها

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

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

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

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

    توجه: روند تایید 1-2 ماه طول می کشد. درخواست های افزایش سهمیه خود را بر این اساس برنامه ریزی کنید. برای آمادگی برای افزایش سهمیه انتخابات ریاست جمهوری 2024، درخواست های سهمیه را تا ماه اوت ارسال کنید.

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

دستورالعمل های داده های اضافی

کار با این داده ها به ویژه دشوار است. لطفا نکات زیر را در نظر داشته باشید.

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

انتساب

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

  • ارائه شده توسط Civic Information API
  • "اطلاعات رای گیری توسط Civic Information API"
  • "اطلاعات رای گیری توسط Civic Information API"
  • "اطلاعات نماینده ارائه شده توسط Civic Information API"
  • "بیشتر بدانید"

کدهای وضعیت

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

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