Historial

El extremo history proporciona información histórica por hora sobre la calidad del aire de una ubicación específica, para un período determinado, hasta un máximo de 30 días. Puedes controlar qué ICA y información pertinente se devuelve (como el nivel de concentración de contaminantes y recomendaciones de salud).

Para solicitar el historial de la calidad del aire por hora con el extremo history, envía una solicitud HTTP POST a la siguiente dirección:

https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY

Incluye tus opciones de solicitud en el cuerpo de la solicitud de JSON. El cuerpo de la solicitud contiene la ubicación y el período para el que deseas obtener el historial de calidad del aire por hora. También puede incluir varias opciones para controlar qué información de calidad del aire se incluirá en la respuesta.

El Explorador de APIs te permite realizar solicitudes en vivo para que puedas familiarizarte con la API y sus opciones:

Pruébalo

Ejemplo de una solicitud de una sola hora

Cuerpo de la solicitud de una hora

En el siguiente código, se muestra cómo crear un cuerpo de solicitud para una solicitud de historial de una sola hora con el método history. En este ejemplo, configuras la ubicación y la marca de tiempo anterior.

Nota: Asegúrate de que el parámetro dateTime especifique un período dentro de los últimos 30 días.

curl -X POST -d '{
  "dateTime": "2023-06-26T15:01:23Z",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Respuesta en una hora

La llamada anterior genera la siguiente respuesta JSON. Para obtener más detalles sobre los datos de respuesta, consulta Datos de respuesta.

Nota: De forma predeterminada, la respuesta incluye el ICA universal con la información básica del ICA. Para quitar el ICA o reemplazarlo por uno diferente, configura los parámetros correspondientes.

{
    "hoursInfo": [
        {
            "dateTime": "2023-06-26T15:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 73,
                    "aqiDisplay": "73",
                    "color": {
                        "red": 118,
                        "green": 202,
                        "blue": 51,
                        "alpha": 255
                    },
                    "category": "Good air quality",
                    "dominantPollutant": "pm10"
                }
            ]
        }
    ],
    "regionCode": "us"
}

Nota: Si el valor de un campo color es 0, ese campo se omite de la respuesta.

Ejemplo de solicitud de intervalo

Solicitud de intervalo de tiempo

En el siguiente código, se muestra cómo crear un cuerpo de solicitud para un history que muestra varios registros de la calidad del aire histórica por hora.

Para solicitar varios registros, especifica un intervalo de tiempo, es decir, una marca de tiempo de inicio y de finalización, o bien especifica la cantidad de horas anteriores a la hora actual.

Nota: Los resultados se muestran en páginas, y los más recientes se muestran en la primera página. Usa la propiedad pageSize para controlar la cantidad máxima de resultados por página. Si se requiere más de una página para recuperar todos los resultados, cada página incluye la propiedad nextPageToken que contiene el token que usas para recuperar la página posterior.

En el siguiente ejemplo, como configuraste el tamaño de la página en 2, tu solicitud de cuatro horas de historial de calidad del aire se muestra en dos páginas, cada una de las cuales contiene dos horas de datos.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Puedes realizar una solicitud similar pasando las marcas de tiempo de inicio y finalización:

Nota: Asegúrate de que los parámetros startTime y endTime especifiquen un período dentro de los últimos 30 días.

curl -X POST -d '{
  "period": {
      "startTime":"2023-06-15T08:00:00Z",
      "endTime":"2023-06-15T12:00:00Z"
  },
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Respuesta del intervalo de tiempo

Las llamadas anteriores generan una respuesta JSON en el siguiente formato. Para obtener más detalles sobre los datos de respuesta, consulta Datos de respuesta.

Ambas llamadas anteriores solicitan datos de calidad del aire de cuatro horas. Sin embargo, como configuraste la propiedad pageSize en 2 en la solicitud, la respuesta solo incluye los resultados de las dos horas más recientes.

{
    "hoursInfo": [
        {
            "dateTime": "2023-06-15T11:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 83,
                    "aqiDisplay": "83",
                    "color": {
                        "red": 74,
                        "green": 185,
                        "blue": 54,
                        "alpha": 255
                    },
                    "category": "Excellent air quality",
                    "dominantPollutant": "o3"
                }
            ]
        },
        {
            "dateTime": "2023-06-15T10:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 89,
                    "aqiDisplay": "89",
                    "color": {
                        "red": 48,
                        "green": 175,
                        "blue": 55,
                        "alpha": 255
                    },
                    "category": "Excellent air quality",
                    "dominantPollutant": "o3"
                }
            ]
        }
    ],
    "regionCode": "us",
    "nextPageToken": "ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA"
}

Ten en cuenta que la respuesta también incluye la propiedad nextPageToken. Usa esta propiedad para acceder a la siguiente página de resultados, que contiene las siguientes dos horas de datos.

Para acceder a la siguiente página de resultados, realiza una segunda solicitud al extremo history, pero esta vez establece la propiedad pageToken en el valor de nextPageToken de la primera respuesta.

Nota: Cuando pases la propiedad pageToken para acceder a páginas de datos posteriores, todos los demás parámetros de la solicitud deben coincidir con la llamada original que proporcionó el token de página.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'