get-historical-observations-by-reporting-area-by-lat-long

Retrieve historical air quality index (AQI) values and categories for a specific location using latitude and longitude, with data available in CSV, JSON, or XML formats. Ideal for analyzing past air quality trends in a reporting area or nearby regions.

Instructions

Get historical AQI values and categories for a reporting area by latitude and longitude.

Input Schema

TableJSON Schema

Name	Required	Description
`date`	Yes	Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01
`distance`	No	If no reporting area is associated with the latitude and longitude, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150
`format`	Yes	Format of the payload file returned. Example: application/json
`latitude`	Yes	Latitude in decimal degrees. Example: 38.33
`longitude`	Yes	Longitude in decimal degrees. Example: -122.28

Implementation Reference

src/tools/historical-observations-by-reporting-area-by-lat-long.ts:33-57 (handler)

The MCP tool handler function that calls the AirNow API helper to fetch historical observations and returns the result as text content or an error message.

async (params) => {
  const result =
    await airnowApi.fetchHistoricalObservationsByReportingAreaByLatLong(
      params
    );
  if (result === null) {
    return {
      content: [
        {
          type: "text",
          text: "Failed to fetch historical observations data from AirNow API.",
        },
      ],
      isError: true,
    };
  }
  return {
    content: [
      {
        type: "text",
        text: result,
      },
    ],
  };
}

src/tools/historical-observations-by-reporting-area-by-lat-long.ts:9-32 (schema)

Zod schema defining the input parameters for the tool: latitude, longitude, date, format, and optional distance.

{
  latitude: z
    .string()
    .describe("Latitude in decimal degrees. Example: 38.33"),
  longitude: z
    .string()
    .describe("Longitude in decimal degrees. Example: -122.28"),
  date: z
    .string()
    .describe(
      "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01"
    ),
  format: z
    .enum(["text/csv", "application/json", "application/xml"])
    .describe(
      "Format of the payload file returned. Example: application/json"
    ),
  distance: z
    .string()
    .optional()
    .describe(
      "If no reporting area is associated with the latitude and longitude, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
    ),
},

src/tools/historical-observations-by-reporting-area-by-lat-long.ts:6-58 (registration)

Registration of the tool on the MCP server within the registerHistoricalObservationsByLatLong function, specifying name, description, input schema, and handler.

server.tool(
  "get-historical-observations-by-reporting-area-by-lat-long",
  "Get historical AQI values and categories for a reporting area by latitude and longitude.",
  {
    latitude: z
      .string()
      .describe("Latitude in decimal degrees. Example: 38.33"),
    longitude: z
      .string()
      .describe("Longitude in decimal degrees. Example: -122.28"),
    date: z
      .string()
      .describe(
        "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01"
      ),
    format: z
      .enum(["text/csv", "application/json", "application/xml"])
      .describe(
        "Format of the payload file returned. Example: application/json"
      ),
    distance: z
      .string()
      .optional()
      .describe(
        "If no reporting area is associated with the latitude and longitude, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150"
      ),
  },
  async (params) => {
    const result =
      await airnowApi.fetchHistoricalObservationsByReportingAreaByLatLong(
        params
      );
    if (result === null) {
      return {
        content: [
          {
            type: "text",
            text: "Failed to fetch historical observations data from AirNow API.",
          },
        ],
        isError: true,
      };
    }
    return {
      content: [
        {
          type: "text",
          text: result,
        },
      ],
    };
  }
);

src/tools/index.ts:21-21 (registration)
Call to register this specific tool within the overall tools registration in src/tools/index.ts.
```
registerHistoricalObservationsByLatLong(server);
```

src/airnow-api.ts:74-84 (helper)

Helper function that constructs the AirNow API request for historical observations by lat/long and fetches the data using the shared airnowGet function.

export async function fetchHistoricalObservationsByReportingAreaByLatLong(params: Record<string, string>): Promise<string | null> {
  const endpoint = 'aq/observation/latlong/historical/';
  const queryParams = new URLSearchParams();
  queryParams.append('latitude', params.latitude);
  queryParams.append('longitude', params.longitude);
  queryParams.append('date', params.date);
  queryParams.append('format', params.format);
  if (params.distance) queryParams.append('distance', params.distance);

  return airnowGet(endpoint, queryParams);
}

AirNow MCP Server