Wytyczne dla deweloperów dotyczące danych

Informacje o głosowaniu

Interfejs Google Civic Information API zwraca użytkownikom informacje o wyborach, takie jak miejsce głosowania, miejsce wcześniejszego głosowania, dane kontaktowe lokalnego urzędnika wyborczego i informacje o karcie do głosowania. Dotyczy to wyborów obsługiwanych przez Voting Information Project.

Dostępność danych

Wskazówki dla programistów

Wymagamy od wszystkich deweloperów przestrzegania tych wytycznych:

  • Przestrzegaj warunków korzystania z interfejsów API.
  • Korzystając z interfejsu API, deweloperzy zgadzają się przestrzegać nagłówków kontroli pamięci podręcznej, jeśli takie istnieją. W przypadku braku nagłówków cache-control deweloperzy zgadzają się nie buforować informacji o lokalach wyborczych i konkursach dłużej niż przez 24 godziny, a informacji o osobach sprawujących urząd i okręgach dłużej niż przez 30 dni.
  • Deweloperzy korzystający z interfejsu API powinni dokładać wszelkich starań, aby zapewnić wszystkim użytkownikom takie same wrażenia. Nie zezwalamy na grupy kontrolne, testy A/B ani podobne eksperymenty.

  • Jeśli potrzebujesz dodatkowego limitu, aby włączyć swój przypadek użycia, możesz poprosić o zwiększenie limitu dla poszczególnych projektów w Developer Console. Dodatkowe przydziały są ograniczone i podlegają maksymalnemu limitowi.

    Uwaga: proces zatwierdzania trwa 1–2 miesiące.Odpowiednio zaplanuj prośby o zwiększenie limitu. Aby przygotować się na zwiększenie limitów w związku z wyborami prezydenckimi w 2024 r., prześlij prośby o zwiększenie limitu do sierpnia.

  • Dodatkowy limit interfejsu Civic Information API jest przeznaczony wyłącznie do obsługi przypadków użycia skierowanych do użytkowników. W przypadku innych zastosowań nie uwzględniamy próśb o zwiększenie limitu.

Dodatkowe wytyczne dotyczące danych

Praca z tymi danymi jest szczególnie trudna. Pamiętaj o tych kwestiach:

  • Urzędnicy wyborczy często weryfikują te dane w ciągu kilku tygodni, a nawet kilku dni przed wyborami. Warto ostrzec użytkowników, aby przed głosowaniem sprawdzili, czy nie pojawiły się nowe informacje.
  • Większość oficjalnych plików danych zawiera segmenty ulic, co oznacza, że urzędnicy wyborczy przypisują zakres adresów do okręgów wyborczych i lokali wyborczych. W tych zakresach mogą być zarejestrowani wyborcy, ale nie muszą. W związku z tym w przypadku stanów, które udostępniają oficjalne pliki danych w ramach projektu Voting Information Project, adres, pod którym nie ma zarejestrowanych wyborców, może zwrócić wynik pozytywny.
  • W przypadku stanów, które nie udostępniają oficjalnego pliku danych, tylko adresy, pod którymi zarejestrowany jest wyborca, będą zwracać wynik pozytywny.
  • Czasami mamy wiele źródeł tych samych informacji. Wyświetlamy informacje najwyższej jakości dotyczące danych kontaktowych lokalnych urzędników wyborczych i informacji o kartach do głosowania. Nie można zastąpić tego działania w inny sposób niż przez wyeliminowanie nieoficjalnych źródeł za pomocą parametru officialSourcesOnly. W przypadku informacji o lokalach wyborczych zawsze traktujemy priorytetowo oficjalne źródła danych.
  • Jeśli wykryjemy problemy z jakością danych, możemy nie zwracać żadnych danych dla danego okręgu wyborczego, dopóki problem nie zostanie rozwiązany.
  • Jeśli nie mamy danych o danym adresie, nie musi to oznaczać, że nikt nie jest tam zarejestrowany jako wyborca. Aplikacje powinny kierować użytkowników do lokalnych urzędników wyborczych, aby uzyskać pełne informacje.
  • Wybory wygasają automatycznie po dniu wyborów. Po tym czasie nie będą zwracane żadne dane dotyczące wyborów.

Atrybucja

Atrybucja do interfejsu Civic Information API jest opcjonalna. Jeśli deweloper zdecyduje się przypisać dane do interfejsu Civic Information API i przekierowywać użytkowników do dodatkowych informacji o tym interfejsie, musi użyć jednego z tych sformułowań i linku do strony internetowej podanego poniżej:

  • „Powered by the Civic Information API”
  • „Informacje o głosowaniu dostarczane przez interfejs Civic Information API”
  • „Informacje o głosowaniu pochodzące z interfejsu Civic Information API”
  • „Więcej informacji”

Kody stanu

Wywołania funkcji voterInfoQuery zawierają pole status, które jest ustawione na success, gdy adres zostanie zaakceptowany. W innych przypadkach zwracany jest kod błędu. Poniżej znajdziesz typowe wyjaśnienia kodów błędów. Pamiętaj, że informacje mogą być zwracane nawet wtedy, gdy występuje kod błędu.

Stan Wyjaśnienie
success Interfejs API rozpoznaje adres z żądania jako prawidłowy.
noStreetSegmentFound Interfejs API nie ma obecnie informacji o tym, do jakiego okręgu wyborczego należy ten adres. Może to oznaczać, że nadal pozyskujemy lub przetwarzamy nowe dane albo że pod tym adresem nie ma zarejestrowanych wyborców.
addressUnparseable Żądany adres jest nieprawidłowo sformatowany lub nie można go geokodować (tzn. interfejs API Map Google nie ma informacji o tym adresie).
noAddressParameter Nie podano adresu.
multipleStreetSegmentsFound Interfejs API nie może znaleźć informacji o określonym adresie, ale ma informacje o adresach w pobliżu. Aby uzyskać więcej informacji, użytkownik powinien skontaktować się z odpowiednim urzędnikiem wyborczym.
electionOver Wybory, których dotyczy prośba, już się zakończyły. Wyniki wyborów w interfejsie API nie są już dostępne. Wyślij zapytanie electionQuery, aby znaleźć identyfikator nadchodzących wyborów.
electionUnknown Identyfikator wyborów w żądaniu jest nieprawidłowy. Wyślij zapytanie electionQuery, aby znaleźć prawidłowy identyfikator.
internalLookupFailure Podczas przetwarzania żądania wystąpił nieokreślony błąd.