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

Địa lý chính trị và số đại diện được bầu

API thông tin dân sự của Google cung cấp thông tin về các bộ phận địa lý chính trị và đại diện được bầu cho các địa chỉ tại Hoa Kỳ từ cấp liên bang đến cấp địa phương. Hiện tại, Google có phạm vi bao phủ đạt gần 100% cho các quận cấp tiểu bang, hạt và hạt Quốc hội, và hướng đến mục tiêu vượt quá 90% phạm vi bao phủ cho các quận lập pháp của tiểu bang. Các cấp thấp hơn, chẳng hạn như hội đồng thành phố và hạt, được phục vụ trên cơ sở nỗ lực tối đa và sẽ cải thiện theo thời gian.

Chúng tôi hy vọng có được thông tin cập nhật về tất cả viên chức được bầu ở cấp liên bang, tiểu bang và hạt, cũng như các quan chức thành phố của thành phố lớn nhất mỗi Tiểu bang của Hoa Kỳ cũng như bất kỳ thành phố nào có dân số lớn hơn 250.000 người. Chúng tôi tổng hợp dữ liệu này từ nhiều nguồn và cung cấp thông tin có chất lượng cao nhất hiện có. Nếu phát hiện vấn đề về chất lượng dữ liệu, chúng tôi có thể ngừng trả về dữ liệu cho các bộ phận địa lý, chức vụ được bầu hoặc quan chức dân cử cụ thể.

Thông tin bỏ phiếu

API Thông tin dân sự của Google trả về thông tin công dân như địa điểm bỏ phiếu, địa điểm bỏ phiếu sớm, thông tin liên hệ của nhân viên bầu cử địa phương và thông tin bỏ phiế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 sử dụng dữ liệu

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

Chúng tôi yêu cầu 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 theo 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, các nhà phát triển đồng ý không lưu vào bộ nhớ đệm quá 24 giờ đối với các địa điểm bỏ phiếu và thông tin cuộc thi, và hơn 30 ngày đối với chủ văn phòng và quận.
  • Các nhà phát triển sử dụng API này phải cố gắng hết sức để đảm bảo tất cả người dùng đều được đáp ứng với cùng một trải nghiệm. Chúng tôi không cho phép quảng cáo bị hạn chế, thử nghiệm A/B hoặc thử nghiệm tương tự.

  • Nếu cần bổ sung 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 từng dự án trong Bảng điều khiển dành cho nhà phát triển. Việc cấp hạn mức bổ sung có giới hạn và tuân theo mức cho phép tối đa.

    Lưu ý: Quá trình phê duyệt kéo dài từ 1 đến 2 tháng.Hãy lên kế hoạch cho 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 bầu cử tổng thống năm 2024,hãy gửi yêu cầu hạn mức chậm nhất vào tháng 8.

  • Hạn mức bổ sung cho API Thông tin dân sự chỉ nhằm hỗ trợ các trường hợp sử dụng dành cho người dùng. Yêu cầu tăng hạn mức sẽ không được cấp 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 ghi nhớ những điểm sau.

  • Các quan chức bầu cử thường sửa đổi dữ liệu này trong vài tuần qua và thậm chí là vài ngày trước khi cuộc bầu cử diễn ra. 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 nguồn cấp dữ liệu chính thức đều chứa các đoạn đường phố, nghĩa là viên chức bầu cử gắn 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ải ô có thể có hoặc không có cử tri nào đăng ký tại các địa chỉ đó. Do đó, đối với các 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ỏ phiếu, một địa chỉ không có cử tri đăng ký nào cũng có thể trở nên thành công.
  • Đối với các 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 được trả về thành công.
  • Đôi khi, chúng tôi sẽ cung cấp cùng một thông tin từ nhiều nguồn. Chúng tôi cung cấp thông tin có chất lượng cao nhất hiện có cho thông tin liên hệ của nhân viên bầu cử địa phương và thông tin trên lá phiế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ố policySourcesOnly. Đố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, có thể chúng tôi sẽ không trả về dữ liệu của 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ì không nhất thiết có nghĩa là không có ai đăng ký bỏ phiếu ở đó. Ứng dụng phải hướng người dùng đến cơ quan 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ử. Sau thời điểm đó, hệ thống sẽ không trả về dữ liệu của cuộc bầu cử.

Phân bổ

Bạn không bắt buộc phải ghi công cho API Thông tin dân sự. Nếu nhà phát triển chọn phân bổ giá trị cho API thông tin dân sự và liên kết người dùng để xem thêm thông tin trên API thông tin dân sự, 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 nhận tác giả và trang web được liên kết bên dưới:

  • "Được cung cấp bởi 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ề bong bóng do API thông tin dân sự cung cấp"
  • "Thông tin đại diện do API Thông tin dân sự hỗ trợ"
  • "Tìm hiểu thêm"

Mã trạng thái

Các lệnh gọi đến voterInfoQuery bao gồm trường status được đặt thành success khi địa chỉ được chấp nhận. Trong các trường hợp khác, hệ thống sẽ trả về mã lỗi. Dưới đây là nội dung giải thích phổ biến 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 Địa chỉ đã yêu cầu được API nhận dạng 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 nào cho địa chỉ này thuộc về. Có thể là chúng tôi vẫn đang tìm nguồn/xử lý dữ liệu mới hoặc chưa có cử tri nào đã đăng ký bỏ phiếu tại địa chỉ này.
addressUnparseable Địa chỉ đã yêu cầu không được định dạng đúng hoặc không thể mã hoá địa lý (tức là API Google Maps không biết bất kỳ điều gì về địa chỉ này).
noAddressParameter Không có địa chỉ nào được cung cấp.
multipleStreetSegmentsFound API không thể tìm thấy thông tin cho địa chỉ được 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ử của họ để biết thêm thông tin.
electionOver Cuộc bầu cử được yêu cầu đã kết thúc. Hiện không còn kết quả API của cuộc bầu cử nữa. Thực hiện electionQuery để tìm mã cho cuộc bầu cử sắp tới.
electionUnknown Mã bầu cử được yêu cầu không hợp lệ. Hãy thực hiện một electionQuery để tìm mã hợp lệ.
internalLookupFailure Đã xảy ra lỗi không xác định trong quá trình xử lý yêu cầu.