Linee guida sui dati degli sviluppatori

Geografia politica e rappresentanti eletti

L'API Google Civic Information offre informazioni su divisioni geografiche politiche e rappresentanti eletti per gli indirizzi statunitensi a livello federale a quello locale. Attualmente, la nostra copertura si avvicina al 100% per i distretti statali, contee e congressuali e puntiamo a superare il 90% per i distretti legislativi statali. I livelli più bassi, come quelli dei consigli comunali e di contea, vengono serviti secondo il criterio del "best effort" e miglioreranno nel tempo.

Prevediamo di disporre di informazioni aggiornate su tutti i funzionari eletti a livello federale, statale e di contea e sui funzionari comunali della città più grande di ogni Stato degli Stati Uniti, nonché di qualsiasi città con più di 250.000 abitanti. Aggreghiamo questi dati da più fonti e pubblichiamo le informazioni disponibili della massima qualità. Se rileviamo problemi di qualità dei dati, potremmo interrompere la restituzione dei dati relativi a determinate divisioni geografiche, cariche elettive o funzionari eletti.

Informazioni sulle votazioni

L'API Google Civic Information restituisce agli utenti informazioni sulle elezioni supportate da Voting Information Project informazioni di carattere civico, come seggio elettorale, luogo del voto anticipato, dati di contatto ufficiali delle elezioni locali e informazioni sulle votazioni.

Disponibilità dei dati

Linee guida per gli sviluppatori

Chiediamo a tutti gli sviluppatori di rispettare le seguenti linee guida:

  • Rispettare i Termini di servizio delle API.
  • Utilizzando l'API, gli sviluppatori accettano di rispettare tutte le intestazioni di controllo della cache, se presenti. In assenza di intestazioni di controllo della cache, gli sviluppatori accettano di non memorizzare nella cache per più di 24 ore per le informazioni sui seggi elettorali e per i concorsi e per più di 30 giorni per funzionari e distretti scolastici.
  • Gli sviluppatori che utilizzano l'API devono fare il possibile per garantire che tutti gli utenti ricevano la stessa esperienza. Non sono ammessi holdback, test A/B o esperimenti simili.

  • Se hai bisogno di un'ulteriore quota per abilitare il tuo caso d'uso, puoi richiedere un aumento per progetto in Play Console. Il provisioning di una quota aggiuntiva è limitato ed è soggetto a un limite massimo.

    Nota: il processo di approvazione richiede uno o due mesi.Pianifica di conseguenza le richieste di aumento della quota. Per prepararti agli aumenti delle quote per le elezioni presidenziali del 2024,invia richieste di quota entro agosto.

  • La quota aggiuntiva per l'API Civic Info è destinata a supportare solo casi d'uso rivolti agli utenti. Le richieste di aumento della quota non sono concesse per altri casi d'uso.

Linee guida aggiuntive sui dati

È particolarmente difficile lavorare con questi dati. Tieni presente quanto segue.

  • I funzionari elettorali rivedeno questi dati spesso nelle ultime settimane e anche negli ultimi giorni prima delle elezioni. Ti consigliamo di avvisare gli utenti che dovrebbero ricontrollare prima di votare.
  • La maggior parte dei feed ufficiali contiene segmenti di strada, il che significa che i funzionari elettorali associano una serie di indirizzi ai distretti e ai seggi elettorali. Gli elettori possono o meno essere registrati a quell'indirizzo. Di conseguenza, per gli stati che forniscono feed ufficiali tramite il Voting Information Project, un indirizzo a cui non sono presenti elettori registrati potrebbe restituire un successo.
  • Per gli stati che non forniscono un feed ufficiale, solo gli indirizzi in cui è presente un elettore registrato potranno restituire un feed ufficiale.
  • A volte, disponiamo di più fonti per le stesse informazioni. Forniamo informazioni di massima qualità disponibili per i dati di contatto e le informazioni sulle votazioni dei funzionari elettorali locali. Non esiste un modo per eseguire l'override di questo comportamento, se non per eliminare le fonti non ufficiali tramite il parametro OfficialSourcesOnly. Per le informazioni sui seggi elettorali, diamo sempre la priorità alle fonti di dati ufficiali rispetto alle altre fonti.
  • Se rileviamo problemi di qualità dei dati, potremmo non restituire dati per un determinato distretto elettorale fino alla risoluzione del problema.
  • Se non disponiamo di dati relativi a un indirizzo, non significa necessariamente che non ci sia nessuno registrato per votare in quel determinato indirizzo. Le domande devono indirizzare gli utenti ai funzionari elettorali locali per avere informazioni complete.
  • Le elezioni scadono automaticamente dopo il giorno delle elezioni. Dopo questo periodo, non verranno restituiti dati sulle elezioni.

Attribuzione

L'attribuzione all'API Civic Information è facoltativa. Se uno sviluppatore sceglie di attribuire gli attributi all'API Civic Information e di collegare gli utenti a ulteriori informazioni sull'API Civic Information, chiediamo agli sviluppatori di utilizzare una delle seguenti lingue di attribuzione e una pagina web collegata tramite il link di seguito:

  • "Con l'API Civic Information"
  • "Informazioni sulle votazioni fornite dall'API Civic Information"
  • "Informazioni fornite dall'API Civic Information"
  • "Informazioni rappresentative basate sull'API Civic Information"
  • "Scopri di più"

Codici di stato

Le chiamate a voterInfoQuery includono un campo status impostato su success quando viene accettato un indirizzo. In altri casi, verrà restituito un codice di errore. Di seguito sono riportate le spiegazioni comuni per i codici di errore. Tieni presente che le informazioni potrebbero essere restituite anche se è presente un codice di errore.

Stato Spiegazione
success L'indirizzo richiesto viene riconosciuto dall'API come indirizzo valido.
noStreetSegmentFound Al momento, l'API non fornisce informazioni sul distretto e/o distretto elettorale a cui appartiene l'indirizzo. È possibile che stiamo ancora approvvigionando/elaborando nuovi dati o che non ci siano elettori che si siano registrati per votare a questo indirizzo.
addressUnparseable L'indirizzo richiesto non è formattato correttamente o non può essere geocodificato (ad esempio, l'API di Google Maps non ha informazioni su questo indirizzo).
noAddressParameter Nessun indirizzo fornito.
multipleStreetSegmentsFound L'API non riesce a trovare informazioni per l'indirizzo specificato, ma contiene informazioni sugli indirizzi vicini. L'utente deve contattare il funzionario elettorale per saperne di più.
electionOver Le elezioni richieste sono terminate. I risultati dell'API per le elezioni non sono più disponibili. Inserisci electionQuery per trovare l'ID di una prossima elezione.
electionUnknown L'ID elettorale richiesto non è valido. Inserisci un valore electionQuery per trovare un ID valido.
internalLookupFailure Si è verificato un errore non specificato durante l'elaborazione della richiesta.