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

Thông tin bỏ phiếu

Google Civic Information API trả về thông tin dân sự (chẳng hạn 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 về lá phiếu) cho người dùng trong các cuộc bầu cử được hỗ trợ bởi Dự án Thông tin Bầu cử.

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 này, nhà phát triển đồng ý tuân thủ mọi tiêu đề cache-control (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 thông tin về người nắm giữ chức vụ 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 mình để đả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 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 để bật 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 là có giới hạn và phải tuân theo hạn mức tối đa.

    Lưu ý: Quá trình phê duyệt 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 trong cuộc bầu cử tổng thống năm 2024,hãy gửi yêu cầu hạn mức trước tháng 8.

  • Hạn mức bổ sung cho Civic Info API chỉ nhằm hỗ trợ các trường hợp sử dụng hướng đến người dùng. Yêu cầu tăng hạn mức sẽ không được chấp thuận cho các trường hợp sử dụng khác.

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

Đây là dữ liệu đặ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 cuối cùng và thậm chí là vài ngày cuối cùng trước cuộc 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ình chọn.
  • Hầu hết 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ử sẽ liên kết một dải địa chỉ với các khu vực bầu cử và địa điểm bỏ phiếu. Các dãy số này có thể có hoặc không có cử tri đă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ó cử tri đã đăng ký mới trả về kết quả thành công.
  • Đôi khi, chúng tôi có nhiều nguồn cho cùng một thông tin. Chúng tôi cung cấp thông tin có chất lượng cao nhất về thông tin liên hệ của quan chức bầu cử địa phương và thông tin về 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 tham 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ỉ, điều đó không nhất thiết có nghĩa là không có ai đăng ký bỏ phiếu tại địa chỉ đó. Các ứng dụng nên chuyển hướng người dùng đến các quan chức bầu cử tại địa phương để biết thông tin đầy đủ.
  • Các cuộc bầu cử sẽ tự động hết hạn sau ngày bầu cử. Sau thời điểm đó, sẽ không có dữ liệu nào được trả về cho cuộc bầu cử.

Phân bổ

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

  • "Do Civic Information API cung cấp"
  • "Thông tin bỏ phiếu do Civic Information API cung cấp"
  • "Thông tin về phiếu bầu do Civic Information API 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, mã lỗi sẽ được trả về. Dưới đây là nội dung giải thích thường gặp về 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à một đị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ể là chúng tôi vẫn đang tìm kiếm/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ả bầu cử qua API không còn nữa. Tạo một electionQuery để tìm mã nhận dạng cho một cuộc bầu cử sắp tới.
electionUnknown Mã bầu cử được yêu cầu không hợp lệ. Tạo một electionQuery để tìm một 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.