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

Instructions

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);
  }