Cette page a été traduite par l'API Cloud Translation.

Utiliser l'API

Ce document décrit ce que vous devez savoir pour utiliser l'API Google Civic Information. Vous pouvez consulter les questions fréquentes sur l'API Civic Info, qui contiennent des informations de base sur l'API, ainsi que les questions fréquentes de notre forum utilisateur. Vous trouverez également ci-dessous des exemples de recherches d'informations sur les électeurs lors d'une élection.

Identifier votre application auprès de Google

Votre application doit s'identifier chaque fois qu'elle envoie une requête à l'API Google Civic Information en incluant une clé API avec chaque requête.

Obtenir et utiliser une clé API

Pour obtenir une clé API :

Ouvrez la page Identifiants dans la console API.
Deux types d'identifiants sont disponibles pour cette API. Créez les identifiants adaptés à votre projet :
- OAuth 2.0 : chaque fois que votre application demande des données utilisateur privées, elle doit envoyer un jeton OAuth 2.0 en même temps que la requête. Votre application envoie d'abord un identifiant client, puis éventuellement un code secret du client pour obtenir un jeton. Vous pouvez générer des identifiants OAuth 2.0 pour des applications Web, des comptes de service ou des applications installées.
  
  Remarque:Étant donné qu'aucune méthode de cette API ne nécessite d'autorisation OAuth 2.0, vous devrez peut-être n'obtenir que des clés API, décrites ci-dessous. Toutefois, si votre application appelle d'autres API qui nécessitent une autorisation de l'utilisateur, vous avez toujours besoin d'identifiants OAuth 2.0.
  
  Pour en savoir plus, consultez la documentation OAuth 2.0.
- Clés API : une demande qui ne fournit pas de jeton OAuth 2.0 doit envoyer une clé API. Cette clé identifie votre projet et vous donne accès à l'API, aux quotas et aux rapports.
  
  L'API propose plusieurs types de restrictions applicables aux clés API. Si la clé API requise n'existe pas déjà, créez-en une dans la console en cliquant sur Créer des identifiants > Clé API. Vous pouvez restreindre la clé avant de l'utiliser en production en cliquant sur Restreindre la clé et en sélectionnant l'une des restrictions.

Pour sécuriser vos clés API, suivez les bonnes pratiques pour utiliser des clés API en toute sécurité.

Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey à toutes les URL de requête.

La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.

Restrictions de clé API

Votre clé API n'est pas limitée par défaut, ce qui n'est pas sécurisé si quelqu'un peut lire cette clé (si elle est placée dans un navigateur, par exemple) ou accéder à l'appareil sur lequel elle est placée. Nous vous recommandons d'appliquer une restriction à cette clé API pour empêcher toute utilisation non autorisée.

Pour ajouter une restriction, cliquez sur Restreindre la clé dans la boîte de dialogue Clé API créée. Le panneau de configuration de la clé API s'affiche:

Le type de restriction que vous sélectionnez dépend des besoins de votre application:

Les applications Web qui interagissent directement avec l'API (c'est-à-dire sans backend ni middleware) doivent ajouter une restriction de référents HTTP. Notez toutefois que ces applications exposent publiquement leur clé API. Nous vous recommandons plutôt d'utiliser un schéma d'authentification de compte de service.
Les applications backend qui ne peuvent pas prendre en charge les comptes de service (par exemple, les appareils intégrés qui ne disposent pas d'un langage compatible dans la bibliothèque cliente) doivent ajouter une restriction d'adresses IP pour se protéger contre l'utilisation par des clients disposant d'adresses IP différentes.
Les applications Android doivent ajouter une restriction Applications Android, ainsi que le nom de votre package et l'empreinte du certificat de signature SHA-1.
Les applications iOS doivent ajouter une restriction Applications iOS et des identifiants de bundle iOS pour limiter les appels d'API à ces bundles iOS.

Pour les tests, vous pouvez ne pas appliquer de restriction du tout. Toutefois, nous vous recommandons d'ajouter une restriction à cette clé ou de la supprimer une fois que vous avez déployé votre application en production.

Exemple electionQuery

Voici un exemple (à l'aide de la version 2 de l'API) d'appel de l'API electionQuery pour obtenir une liste d'ID d'élection valides, puis de l'API voterInfoQuery avec l'adresse enregistrée d'un électeur pour obtenir des informations sur une élection sélectionnée.

Utilisez electionQuery pour obtenir la liste des ID d'élection valides:

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

Réponse de 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 avec curl

Utilisez curl pour envoyer une requête voterInfoQuery pour l'ID d'élection de test VIP 2000 et l'électeur à l'adresse (test) 340 Main St, Venice, CA 90291. Vous pouvez consulter la réponse de la requête voterInfoQuery.

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

voterInfoQuery à l'aide de la bibliothèque cliente des API Google pour JavaScript

Cet exemple émet la même requête voterInfoQuery que l'exemple curl précédent, mais il utilise la bibliothèque cliente JavaScript. La réponse voterInfoQuery est identique à la réponse de l'exemple 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>

Réponse de 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
          }
        ]
      }
    }
  ]
}

Utiliser l'API Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.