Configura la API de Address Validation

Desarrolladores del Espacio Económico Europeo (EEE)

En este documento, se describen los pasos que debes seguir para comenzar a usar la API de Address Validation.

Requisitos previos

Este procedimiento te guiará para configurar una cuenta de Google Cloud y un proyecto de Google Cloud con la facturación habilitada. También debes conocer cómo se te cobra por usar la API de Address Validation.

  1. Revisa la facturación y el costo por uso en Uso y facturación de la API de Address Validation.

  2. Verifica que tengas una Cuenta de Google Cloud.

    Accede a la consola de Google Cloud

  3. Verifica que tengas un proyecto de Google Cloud con la facturación habilitada.

    Ir a la página Facturación
    1. Selecciona tu proyecto para abrir la página Facturación.

    2. En la página Facturación, haz lo siguiente:

      • Si la facturación ya está habilitada para el proyecto seleccionado y solo tienes una cuenta de facturación, se abrirá la página Facturación.
      • Si tienes varias cuentas de facturación, selecciona Ir a la cuenta de facturación vinculada para ver los detalles de la cuenta de facturación asociada con el proyecto.
      • Si existe una cuenta de facturación, pero no está asociada al proyecto, se te solicitará que vincules una cuenta de facturación con el proyecto.
      • Si no existe una cuenta de facturación o quieres crear una nueva, selecciona Administrar cuentas de facturación para crear una nueva. Para obtener más información, consulta Crea una nueva cuenta de Facturación de Cloud de servicio automático.

Habilita la API

Antes de poder usar la API de Address Validation, debes usar la consola de Google Cloud o el comando gcloud para habilitarla en tu proyecto de Google Cloud.

Para habilitar la API, sigue estos pasos:

Console

  1. Abre la página del producto en la consola de Google Cloud:

    Habilita la API de Address Validation

  2. Haz clic en el botón Habilitar.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com"

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

Obtén una clave de API para usarla con la API de Address Validation

Los productos de Google Maps Platform están protegidos contra un uso no autorizado porque requieren que las llamadas a la API incluyan una clave de API o un token de OAuth. Primero, se debe realizar el procedimiento de la clave de API. Para usar un token de OAuth, consulta Crea un token de OAuth.

Una clave de API es una cadena alfanumérica única que asocia tu cuenta de Facturación de Cloud y tu proyecto de Google Cloud con la solicitud que tu aplicación realiza a una API o un SDK de Google Maps Platform. Para crear una clave nueva o agregar una API o un SDK a una clave existente, sigue estas instrucciones.

Console

  1. Ve a la página Google Maps Platform > Claves y credenciales.

    Ir a la página Claves y credenciales

  2. Si se solicita, selecciona tu proyecto.

  3. Realiza una de las siguientes acciones:

    • Crea una clave nueva:

      1. Haz clic en Crear credenciales > Clave de API.
      2. En el panel Crear clave de API, abre la lista Elige las restricciones de API.
      3. Borra las APIs que no necesite esta clave y asegúrate de que la API de Address Validation permanezca seleccionada.
      4. Haz clic en Crear. En el panel, se mostrará tu nueva clave de API.

    • Usar una clave existente:

      1. Haz clic en el nombre de la clave.
      2. En la lista Selecciona las restricciones de API, elige API de Address Validation.
      3. Haz clic en Guardar.

    Seleccionar una API aquí no la habilita. Asegúrate de que la API de Address Validation esté habilitada en su página de la biblioteca de APIs.

  4. Para ver la cadena de clave más adelante, ve a la página Claves y credenciales y haz clic en Mostrar clave para la clave.

Si la consola se ve diferente de estos pasos, consulta Crea una clave de API y Agrega restricciones de API en la documentación de Google Cloud.

gcloud

Reemplaza PROJECT_ID por el ID del proyecto en los siguientes comandos.

  • Crea una clave nueva: Ejecuta el siguiente comando y reemplaza DISPLAY_NAME por un nombre para la clave. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=addressvalidation.googleapis.com

    Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

  • Usa una clave existente: Ejecuta el siguiente comando y reemplaza KEY_ID por el ID de la clave. La marca --append conserva las APIs que la clave ya permite. Sin él, el comando las reemplaza.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=addressvalidation.googleapis.com

    Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

    El ID de clave no es la cadena de clave ni el nombre visible. Para encontrarlo, ejecuta gcloud services api-keys list --project="PROJECT_ID". El ID es la última parte del campo name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Para ver la cadena de la clave, ejecuta gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Realiza una solicitud a la API

Realiza una solicitud a la API de Address Validation para que devuelva una respuesta JSON que valide la dirección "1600 Amphitheatre Parkway, Mountain View, CA". Debes incluir la cadena alfanumérica de tu clave de API en cada solicitud y usar HTTPS para las solicitudes que incluyan la clave de API.

  1. Haz clic en API_KEY en el siguiente código para insertar la cadena alfanumérica de la clave:

    curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=API_KEY"
  2. Haz clic en el ícono de copia en la muestra de código, Selecciona el ícono de copiar., para copiar el comando curl.
  3. Pega el comando en una ventana de terminal y ejecútalo.

La respuesta es un objeto JSON con el siguiente formato:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "a3d051f9-a802-4d8a-b530-46ee45903453"
}

Aplica restricciones de claves de API

Google recomienda que restrinjas las claves de API limitando su uso solo a las APIs y las apps que las necesitan. La restricción de las claves de API agrega seguridad a tu aplicación, ya que la protege de solicitudes no autorizadas. Las claves de API admiten dos tipos de restricciones:

  • Las restricciones de API especifican a qué SDKs y APIs se puede llamar con la clave de API. La consola y gcloud CLI requieren al menos una restricción de API cuando creas una clave.
  • Las restricciones de aplicaciones especifican qué sitios web, direcciones IP o apps pueden usar una clave de API.

Para obtener más información sobre cómo aplicar restricciones, consulta Restringe tus claves de API.

Crea un token de OAuth

La API de Address Validation admite OAuth 2.0 para la autenticación. Google admite situaciones comunes de OAuth 2.0, como las de un servidor web.

En este documento, se describe cómo pasar un token de OAuth a una llamada a la API de Address Validation en tu entorno de desarrollo. Para obtener más información sobre el uso de OAuth en un entorno de producción, consulta Métodos de autenticación en Google.

Puedes llamar a las APIs de Google Maps directamente realizando solicitudes a la API al servidor, o bien puedes usar bibliotecas cliente para simplificar tu código. Google Maps proporciona bibliotecas cliente para Go, Java, Node.js y Python. Para obtener más información, consulta las bibliotecas cliente de la API de Address Validation.

Descripción general de OAuth

Puedes crear y administrar tokens de acceso con OAuth de varias maneras, según tu entorno de implementación.

Puedes usar OAuth 2.0 para las interacciones de servidor a servidor entre tu aplicación y un servicio de Google. En este caso, usarás una cuenta de servicio asociada con tu aplicación, en lugar de un usuario individual. Puedes realizar solicitudes a la API con la cuenta de servicio sin involucrar a los usuarios directamente. Para obtener más información sobre los métodos de autenticación, consulta Métodos de autenticación en Google.

Como alternativa, puedes integrar la API de Address Validation en una app para dispositivos móviles con iOS o Android. Para obtener más información sobre cómo usar OAuth y administrar tokens de acceso para diferentes entornos de implementación, consulta Usa OAuth 2.0 para acceder a las APIs de Google.

Alcances de OAuth

Para usar OAuth con la API de Address Validation, debes asignar al token de OAuth el siguiente permiso:

https://www.googleapis.com/auth/cloud-platform

Ejemplo: Prueba las llamadas a la API de REST en tu entorno de desarrollo local

Si no tienes un entorno que genere tokens y quieres probar la API de Address Validation con un token de OAuth, usa el procedimiento que se indica en esta sección.

En este ejemplo, se describe cómo usar el token de OAuth que proporcionan las credenciales predeterminadas de la aplicación (ADC) para realizar la llamada. Para obtener más información sobre el uso de ADC para llamar a las APIs de Google con bibliotecas cliente, consulta Autentícate con bibliotecas cliente.

Usa el siguiente procedimiento de REST solo para desarrollo o pruebas, no para producción.

Requisitos previos

Antes de realizar una solicitud REST con ADC, usa la CLI de gcloud para proporcionar credenciales a ADC:

  1. Instala e inicializa la CLI de gcloud Para obtener más información, consulta Instala gcloud CLI.

  2. Autentica con la CLI de gcloud:

    gcloud auth application-default login

  3. Completa el proceso de acceso para guardar tus credenciales en el archivo de credenciales local que usa ADC.

Para obtener más información, consulta Configura ADC para un entorno de desarrollo local.

Realiza una solicitud de REST

En este ejemplo, pasas dos encabezados de solicitud:

  • Pasa el token de OAuth en el encabezado Authorization con el siguiente comando para generar el token:

    gcloud auth application-default print-access-token

    El token que se muestra tiene un alcance de https://www.googleapis.com/auth/cloud-platform.

  • Pasa el ID o el nombre de tu proyecto de Google Cloud que tiene habilitada la facturación en el encabezado X-Goog-User-Project.

Para llamar a la API de Address Validation con un token de OAuth, completa los siguientes pasos:

  1. En la siguiente muestra de código, reemplaza PROJECT_ID por tu ID del proyecto de Google Cloud:

    curl -X POST -d '{
"address": {
"regionCode": "US",
"locality": "Mountain View",
"addressLines": ["1600 Amphitheatre Pkwy"]
}
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://addressvalidation.googleapis.com/v1:validateAddress"

  2. Para copiar el comando curl, haz clic en Copiar en la muestra de código.

  3. Pega el comando en una ventana de terminal y, luego, ejecútalo.

La respuesta es un objeto JSON:

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4225022,
        "longitude": -122.0847398
      },
      "plusCode": {
        "globalCode": "849VCWF8+24"
      },
      "bounds": {
        "low": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        },
        "high": {
          "latitude": 37.4225022,
          "longitude": -122.0847398
        }
      },
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeTypes": [
        "street_address"
      ]
    },
    "metadata": {
      "business": true,
      "residential": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S",
      "dpvNoStatReasonCode": 5,
      "dpvDrop": "N",
      "dpvThrowback": "N",
      "dpvNonDeliveryDays": "N",
      "dpvNoSecureLocation": "N",
      "dpvPbsa": "N",
      "dpvDoorNotAccessible": "N",
      "dpvEnhancedDeliveryCode": "Y"
    }
  },
  "responseId": "fac2ae1b-50ce-442c-8bc3-d459039950ef"
}

Solución de problemas

Si tu solicitud muestra un mensaje de error que indica que esta API no admite credenciales de usuario final, consulta Soluciona problemas de la configuración de ADC.

¿Qué sigue?

Ahora que habilitaste la API de Address Validation y realizaste una solicitud correctamente, consulta Envía una solicitud de validación de dirección y Comprende una respuesta básica de validación de dirección para obtener más información sobre cómo usar la API.