Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzo dell'API

Questo documento descrive ciò che devi sapere per utilizzare l'API Google Civic Information. Puoi consultare queste domande frequenti sull'API Civic Info, che contengono alcune informazioni di base sull'API, nonché le domande frequenti del nostro forum per gli utenti. Inoltre, di seguito puoi trovare alcuni esempi per la ricerca di informazioni sugli elettori durante un'elezione.

Identificazione dell'applicazione per Google

La tua applicazione deve identificarsi ogni volta che invia una richiesta all'API Google Civic Information, includendo una chiave API in ogni richiesta.

Acquisizione e utilizzo di una chiave API

Per acquisire una chiave API:

Apri la pagina Credenziali nella console API.
Questa API supporta due tipi di credenziali. Crea le credenziali appropriate per il tuo progetto:
- OAuth 2.0: ogni volta che la tua applicazione richiede dati utente privati, deve inviare un token OAuth 2.0 insieme alla richiesta. La tua applicazione invia innanzitutto un ID client e, eventualmente, un client secret per ottenere un token. Puoi generare credenziali OAuth 2.0 per applicazioni web, account di servizio o applicazioni installate.
  
  Nota: poiché questa API non ha metodi che richiedono l'autorizzazione OAuth 2.0, potrebbe essere necessario solo ottenere chiavi API, descritte di seguito. Tuttavia, se la tua applicazione chiama altre API che richiedono l'autorizzazione dell'utente, devi comunque disporre delle credenziali OAuth 2.0.
  
  Per ulteriori informazioni, consulta la documentazione di OAuth 2.0.
- Chiavi API: una richiesta che non fornisce un token OAuth 2.0 deve inviare una chiave API. La chiave identifica il progetto e fornisce accesso all'API, quota e report.
  
  L'API supporta diversi tipi di restrizioni per le chiavi API. Se la chiave API di cui hai bisogno non esiste già, creala nella console facendo clic su Crea credenziali > Chiave API. Puoi limitare la chiave prima di utilizzarla in produzione facendo clic su Limita chiave e selezionando una delle Restrizioni.

Per proteggere le tue chiavi API, segui le best practice per l'utilizzo sicuro delle chiavi API.

Una volta ottenuta una chiave API, la tua applicazione può aggiungere il parametro di querykey=yourAPIKey a tutti gli URL di richiesta.

La chiave API è sicura per l'inserimento negli URL e non richiede alcuna codifica.

Limitazioni relative alle chiavi API

La chiave API è senza restrizioni per impostazione predefinita, il che non è sicuro se chiunque può leggere questa chiave (ad esempio se è inserita in un browser) o accedere al dispositivo su cui è inserita. Ti consigliamo di applicare una limitazione a questa chiave API per impedire l'utilizzo non autorizzato.

Per aggiungere una restrizione, fai clic su Limita chiave nella finestra di dialogo Chiave API creata. Viene visualizzato il riquadro di configurazione della chiave API:

Il tipo di restrizione selezionato dipende dalle esigenze della tua applicazione:

Le applicazioni web che interagiscono direttamente con l'API (ovvero non tramite un backend o un middleware) devono aggiungere una limitazione dei referrer HTTP. Tieni presente, tuttavia, che queste applicazioni esporranno la loro chiave API pubblicamente. Ti consigliamo di utilizzare uno schema di autenticazione dell'account di servizio.
Le applicazioni di backend che non possono supportare gli account di servizio in altro modo (ad esempio, i dispositivi embedded che non hanno un linguaggio supportato nella libreria client) devono aggiungere una limitazione degli indirizzi IP per proteggersi dall'utilizzo da parte di client con indirizzi IP diversi.
Le applicazioni per Android devono aggiungere una limitazione per le app per Android e il nome del pacchetto e l'impronta per il certificato di firma SHA-1.
Le applicazioni per iOS devono aggiungere una limitazione per le app per iOS e gli eventuali identificatori dei gruppi iOS per limitare le chiamate API a questi gruppi.

Per i test, ti consigliamo di non applicare alcuna limitazione. Tuttavia, è consigliabile aggiungere una limitazione a questa chiave o eliminarla dopo aver eseguito il deployment dell'applicazione in produzione.

Esempio di electionQuery

Ecco un esempio (che utilizza la versione dell'API "v2") di chiamata dell'API electionQuery per ottenere un elenco di ID elezione validi, quindi dell'API voterInfoQuery con l'indirizzo registrato di un votante per ottenere informazioni su un'elezione selezionata.

Utilizza electionQuery per ottenere un elenco di ID elezione validi:

  https://www.googleapis.com/civicinfo/v2/elections?key=<YOUR_API_KEY>

Risposta di electionQuery:

{
 "kind": "civicinfo#electionsqueryresponse",
 "elections": [
  {
   "id": "2000",
   "name": "VIP Test Election",
   "electionDay": "2013-06-06"
  },
  {
   "id": "2124",
   "name": "Rhode Island 2012 Primary Election",
   "electionDay": "2012-09-11"
  },
  {
   "id": "2126",
   "name": "Delaware 2012 Primary Election",
   "electionDay": "2012-09-11"
  }
 ]
}

voterInfoQuery utilizzando curl

Utilizza curl per inviare una richiesta voterInfoQuery per l'ID elezione di test VIP 2000 e per l'elettore all'indirizzo (di test) 340 Main St, Venice, CA 90291. Puoi fare riferimento alla risposta della query voterInfo.

curl "https://www.googleapis.com/civicinfo/v2/voterinfo?key=<YOUR_API_KEY>&address=340%20Main%20St.%20Venice%20CA&electionId=2000"

voterInfoQuery utilizzando la libreria client dell'API di Google per JavaScript

Questo esempio emette la stessa query voterInfo dell'esempio curl precedente, ma utilizza la libreria client JavaScript. La risposta a voterInfoQuery è la stessa della risposta di esempio di curl.

<!doctype html>
<html>
  <head>
    <script>
      /**
       * Build and execute request to look up voter info for provided address.
       * @param {string} address Address for which to fetch voter info.
       * @param {function(Object)} callback Function which takes the
       *     response object as a parameter.
       */
       function lookup(address, callback) {
       /**
         * Election ID for which to fetch voter info.
         * @type {number}
         */
        var electionId = 2000;
 
        /**
         * Request object for given parameters.
         * @type {gapi.client.HttpRequest}
         */
        var req = gapi.client.request({
            'path' : '/civicinfo/v2/voterinfo',
            'params' : {'electionId' : electionId, 'address' : address}
        });
       req.execute(callback);
      }

      /**
       * Render results in the DOM.
       * @param {Object} response Response object returned by the API.
       * @param {Object} rawResponse Raw response from the API.
       */
      function renderResults(response, rawResponse) {
        var el = document.getElementById('results');
        if (!response || response.error) {
          el.appendChild(document.createTextNode(
              'Error while trying to fetch polling place'));
          return;
        }
        var normalizedAddress = response.normalizedInput.line1 + ' ' +
            response.normalizedInput.city + ', ' +
            response.normalizedInput.state + ' ' +
            response.normalizedInput.zip;
        if (response.pollingLocations.length > 0) {
          var pollingLocation = response.pollingLocations[0].address;
          var pollingAddress = pollingLocation.locationName + ', ' +
              pollingLocation.line1 + ' ' +
              pollingLocation.city + ', ' +
              pollingLocation.state + ' ' +
              pollingLocation.zip;
          var normEl = document.createElement('strong');
          normEl.appendChild(document.createTextNode(
              'Polling place for ' + normalizedAddress + ': '));
          el.appendChild(normEl);
          el.appendChild(document.createTextNode(pollingAddress));
        } else {
          el.appendChild(document.createTextNode(
              'Could not find polling place for ' + normalizedAddress));
        }
      }

      /**
       * Initialize the API client and make a request.
       */
      function load() {
        gapi.client.setApiKey('YOUR API KEY GOES HERE');
        lookup('1263 Pacific Ave. Kansas City KS', renderResults);
      }
    </script>
    <script src="https://apis.google.com/js/client.js?onload=load"></script>
  </head>
  <body>
    <div id="results"></div>
  </body>
</html>

Risposta di voterInfoQuery

{
  "kind": "civicinfo#voterinforesponse",
  "status": "success",
  "election": {
  "id": "2000",
  "name": "VIP Test Election",
  "electionDay": "2025-06-06",
  "ocdDivisionId": "ocd-division/country:us"
  },
  "normalizedInput": {
    "line1": "340 Main Street",
    "city": "Venice",
    "state": "CA",
    "zip": "90291"
  },
  "pollingLocations": [
    {
      "address": {
        "locationName": "WESTMINSTER AVENUE ELEMENTARY SCHOOL",
        "line1": "1010 ABBOT KINNEY BLVD",
        "city": "VENICE",
        "state": "CA",
        "zip": "90291"
      },
      "pollingHours": "",
      "latitude": 33.9919351,
      "longitude": -118.4722031,
      "startDate": "2024-03-05",
      "endDate": "2024-03-05",
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ]
    },
    {
      "address": {
        "locationName": "POP UP VOTE CENTER 5",
        "line1": "12400 IMPERIAL HWY",
        "city": "NORWALK",
        "state": "CA",
        "zip": "90650"
      },
      "latitude": 33.915989,
      "longitude": -118.0677283,
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ]
    }
  ],
  "dropOffLocations": [
    {
      "address": {
        "locationName": "FLEX VOTE CENTER 9",
        "line1": "12400 IMPERIAL HWY",
        "city": "NORWALK",
        "state": "CA",
        "zip": "90650"
      },
      "latitude": 33.915989,
      "longitude": -118.0677283,
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ]
    },
  ],
  "contests": [
    {
      "type": "General",
      "ballotTitle": "UNITED STATES REPRESENTATIVE, 36th District",
      "district": {
        "name": "36TH US CONGRESSIONAL",
        "scope": "congressional"
      },
      "numberElected": "1",
      "numberVotingFor": "1",
      "ballotPlacement": "103",
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ],
      "candidates": [
        {
          "name": "ARIANA HAKAMI",
          "party": "Party Preference: Republican"
        },
        {
          "name": "CLAIRE RAGGE ANDERSON",
          "party": "Party Preference: None"
        },
        {
          "name": "MELISSA TOOMIM",
          "party": "Party Preference: Republican"
        },
        {
          "name": "TED W. LIEU",
          "party": "Party Preference: Democratic"
        }
      ]
    },
    {
      "type": "ballot-measure",
      "ballotTitle": "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA",
      "district": {
        "name": "CITY OF LOS ANGELES",
        "scope": "citywide"
      },
      "ballotPlacement": "116",
      "referendumTitle": "LOS ANGELES CITY MUNICIPAL ELECTION - MEASURE HLA",
      "referendumText": "CITY MOBILITY PLAN STREET IMPROVEMENT MEASURES. INITIATIVE ORDINANCE HLA. Shall an ordinance providing that when the City of Los Angeles makes a qualifying improvement to a City-owned street (e.g., a paving project), the City must also install certain street enhancements described in the City's Mobility Plan network of pedestrian, bicycle, transit, and vehicle routes; and requiring the City to provide publicly accessible information regarding street improvements; be adopted?",
      "referendumPassageThreshold": "MAJORITY OF VOTES CAST",
      "referendumBallotResponses": [
        "YES",
        "NO"
      ],
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ]
    },
    {
      "type": "General",
      "ballotTitle": "DISTRICT ATTORNEY",
      "district": {
        "name": "LOS ANGELES COUNTY",
        "scope": "countywide"
      },
      "numberElected": "1",
      "numberVotingFor": "1",
      "ballotPlacement": "129",
      "sources": [
        {
          "name": "Voting Information Project",
          "official": true
        }
      ],
      "candidates": [
        {
          "name": "GEORGE GASCÓN"
        },
        {
          "name": "JONATHAN HATAMI"
        },
        {
          "name": "NATHAN HOCHMAN"
        },
        {
          "name": "DEBRA ARCHULETA"
        },
        {
          "name": "JEFF CHEMERINSKY"
        },
        {
          "name": "ERIC SIDDALL"
        },
        {
          "name": "MARIA RAMIREZ"
        },
        {
          "name": "DAN KAPELOVITZ"
        },
        {
          "name": "LLOYD \"BOBCAT\" MASSON"
        },
        {
          "name": "JOHN MCKINNEY"
        },
        {
          "name": "CRAIG J. MITCHELL"
        },
        {
          "name": "DAVID S. MILTON"
        }
      ]
    }
  ],
  "state": [
    {
      "name": "California",
      "electionAdministrationBody": {
        "name": "Secretary of State",
        "electionInfoUrl": "https://www.sos.ca.gov/elections/",
        "electionRegistrationUrl": "https://registertovote.ca.gov/?t=s",
        "electionRegistrationConfirmationUrl": "https://voterstatus.sos.ca.gov",
        "absenteeVotingInfoUrl": "https://elections.cdn.sos.ca.gov/vote-by-mail/replacement-application.pdf",
        "votingLocationFinderUrl": "https://voterstatus.sos.ca.gov",
        "ballotInfoUrl": "https://www.sos.ca.gov/elections/ballot-status/wheres-my-ballot/",
        "correspondenceAddress": {
          "line1": "1500 11th Street, 5th Floor",
          "city": "Sacramento",
          "state": "California",
          "zip": "95814"
        }
      },
      "local_jurisdiction": {
        "name": "Los Angeles",
        "electionAdministrationBody": {
          "name": "Registrar-Recorder/County Clerk",
          "electionInfoUrl": "http://www.lavote.gov/",
          "electionRegistrationUrl": "http://registertovote.ca.gov/",
          "electionRegistrationConfirmationUrl": "https://lavote.gov/vrstatus/",
          "absenteeVotingInfoUrl": "",
          "ballotInfoUrl": "http://www.lavote.gov/Locator",
          "physicalAddress": {
            "locationName": "Registrar-Recorder/County Clerk",
            "line1": "12400 Imperial Highway",
            "city": "Norwalk",
            "state": "CA",
            "zip": "90650"
          }
        },
        "sources": [
          {
            "name": "Voting Information Project",
            "official": true
          }
        ]
      }
    }
  ]
}

Utilizzo dell'API Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.