Nguyên tắc về dữ liệu dành cho nhà phát triển

Thông tin bỏ phiếu

Civics Information API của Google trả về thông tin dân sự như địa điểm bỏ phiếu, địa điểm bỏ phiếu sớm, thông tin liên hệ của quan chức bầu cử địa phương và thông tin phiếu bầu cho người dùng đối với các cuộc bầu cử được hỗ trợ bởi Dự án thông tin bỏ phiếu.

Khả năng cung cấp dữ liệu

Nguyên tắc dành cho nhà phát triển

Tất cả nhà phát triển đều phải tuân thủ các nguyên tắc sau:

  • Tuân thủ điều khoản dịch vụ của API.
  • Khi sử dụng API, nhà phát triển đồng ý tuân thủ mọi tiêu đề kiểm soát bộ nhớ đệm nếu có. Nếu không có tiêu đề kiểm soát bộ nhớ đệm, nhà phát triển đồng ý không lưu vào bộ nhớ đệm quá 24 giờ đối với thông tin về địa điểm bỏ phiếu và cuộc thi, cũng như không lưu vào bộ nhớ đệm quá 30 ngày đối với các ứng cử viên và khu vực bầu cử.
  • Nhà phát triển sử dụng API này phải nỗ lực hết sức để đảm bảo tất cả người dùng đều có trải nghiệm như nhau. Chúng tôi không cho phép tính năng giữ lại, thử nghiệm A/B hoặc các thử nghiệm tương tự.

  • Nếu cần thêm hạn mức để hỗ trợ trường hợp sử dụng của mình, bạn có thể yêu cầu tăng hạn mức cho mỗi dự án trong Developer Console. Việc cấp thêm hạn mức bị giới hạn và tuân theo mức cho phép tối đa.

    Lưu ý: Quá trình phê duyệt sẽ mất từ 1 đến 2 tháng.Hãy lên kế hoạch cho các yêu cầu tăng hạn mức cho phù hợp. Để chuẩn bị cho việc tăng hạn mức cho cuộc bầu cử tổng thống năm 2024,hãy gửi yêu cầu tăng hạn mức trước tháng 8.

  • Hạn mức bổ sung cho API Thông tin công dân chỉ nhằm hỗ trợ các trường hợp sử dụng dành cho người dùng. Chúng tôi không chấp nhận các yêu cầu tăng hạn mức cho các trường hợp sử dụng khác.

Nguyên tắc bổ sung về dữ liệu

Dữ liệu này đặc biệt khó xử lý. Vui lòng lưu ý những điểm sau.

  • Các quan chức bầu cử thường xuyên sửa đổi dữ liệu này trong vài tuần và thậm chí là vài ngày cuối cùng trước ngày bầu cử. Bạn nên cảnh báo người dùng rằng họ nên kiểm tra lại trước khi bỏ phiếu.
  • Hầu hết các nguồn cấp dữ liệu chính thức đều chứa các đoạn đường, tức là các quan chức bầu cử liên kết một loạt địa chỉ với các khu vực bầu cử và địa điểm bỏ phiếu. Các dải địa chỉ này có thể có hoặc không có cử tri nào đăng ký tại những địa chỉ đó. Do đó, đối với những tiểu bang cung cấp nguồn cấp dữ liệu chính thức thông qua Dự án thông tin bầu cử, một địa chỉ không có cử tri đã đăng ký có thể trả về kết quả thành công.
  • Đối với những tiểu bang không cung cấp nguồn cấp dữ liệu chính thức, chỉ những địa chỉ có người đã đăng ký bầu cử mới trả về kết quả thành công.
  • Đôi khi, chúng tôi sẽ có nhiều nguồn cho cùng một thông tin. Chúng tôi cung cấp thông tin chất lượng cao nhất hiện có về thông tin liên hệ của cơ quan bầu cử địa phương và thông tin phiếu bầu. Không có cách nào để ghi đè hành vi này, ngoài việc loại bỏ các nguồn không chính thức thông qua thông số officialSourcesOnly. Đối với thông tin về địa điểm bỏ phiếu, chúng tôi luôn ưu tiên các nguồn dữ liệu chính thức hơn các nguồn khác.
  • Nếu phát hiện vấn đề về chất lượng dữ liệu, chúng tôi có thể không trả về dữ liệu cho một khu vực bầu cử cụ thể cho đến khi vấn đề được giải quyết.
  • Nếu chúng tôi không có dữ liệu về một địa chỉ, thì điều đó không có nghĩa là không có ai đăng ký bỏ phiếu tại địa chỉ đó. Ứng dụng phải chuyển hướng người dùng đến các quan chức bầu cử địa phương để biết thông tin đầy đủ.
  • Cuộc bầu cử sẽ tự động hết hạn sau ngày bầu cử. Hệ thống sẽ không trả về dữ liệu nào cho cuộc bầu cử sau thời điểm đó.

Phân bổ

Bạn không bắt buộc phải phân bổ cho API Thông tin công dân. Nếu nhà phát triển chọn ghi công cho API Thông tin công dân và liên kết người dùng đến thông tin khác về API Thông tin công dân, thì chúng tôi yêu cầu nhà phát triển sử dụng một trong các lựa chọn ngôn ngữ ghi công sau đây và trang web được liên kết bên dưới:

  • "Dựa trên API Thông tin dân sự"
  • "Thông tin bỏ phiếu do API Thông tin dân sự cung cấp"
  • "Thông tin về phiếu bầu do API Thông tin dân sự cung cấp"
  • "Tìm hiểu thêm"

Mã trạng thái

Các lệnh gọi đến voterInfoQuery bao gồm một trường status được đặt thành success khi một địa chỉ được chấp nhận. Trong các trường hợp khác, hệ thống sẽ trả về một mã lỗi. Dưới đây là nội dung giải thích phổ biến về các mã lỗi. Xin lưu ý rằng thông tin có thể được trả về ngay cả khi có mã lỗi.

Trạng thái Giải thích
success API nhận dạng địa chỉ được yêu cầu là địa chỉ hợp lệ.
noStreetSegmentFound API hiện không có thông tin về khu vực bầu cử và/hoặc quận mà địa chỉ này thuộc về. Có thể chúng tôi vẫn đang thu thập/xử lý dữ liệu mới hoặc không có cử tri nào đăng ký bỏ phiếu tại địa chỉ này.
addressUnparseable Địa chỉ được yêu cầu có định dạng không chính xác hoặc không thể được mã hoá địa lý (tức là API Google Maps không biết gì về địa chỉ này).
noAddressParameter Bạn chưa cung cấp địa chỉ.
multipleStreetSegmentsFound API không tìm thấy thông tin cho địa chỉ đã chỉ định, nhưng có thông tin về các địa chỉ lân cận. Người dùng nên liên hệ với nhân viên bầu cử để biết thêm thông tin.
electionOver Cuộc bầu cử được yêu cầu đã kết thúc. Kết quả API cho cuộc bầu cử này không còn nữa. Tạo electionQuery để tìm mã nhận dạng cho một cuộc bầu cử sắp tới.
electionUnknown Mã cuộc bầu cử được yêu cầu không hợp lệ. Tạo một electionQuery để tìm mã nhận dạng hợp lệ.
internalLookupFailure Đã xảy ra lỗi không xác định khi xử lý yêu cầu.