Wytyczne dla deweloperów dotyczące danych

Informacje o głosowaniu

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:

  • przestrzegać 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 Google Developers Console. Dodatkowe przydziały są ograniczone i podlegają maksymalnemu limitowi.

    Uwaga: proces zatwierdzania trwa 1–2 miesiące, dlatego zalecamy deweloperom odpowiednie zaplanowanie próśb o zwiększenie limitu. W przypadku zwiększenia limitu na wybory w listopadzie zdecydowanie zalecamy przesyłanie próśb o zwiększenie limitu nie później niż do końca 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ń prośby o zwiększenie limitu nie są uwzględniane.

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 ostatnich 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 przypadku tych zakresów 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 zarejestrowani są wyborcy, będą zwracać wynik pozytywny.
  • Czasami mamy wiele źródeł tych samych informacji. Udostępniamy 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 dotyczących danego adresu, 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 automatycznie wygasają 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ć atrybucję 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 lub obwodu 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 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.