get-current-observations-by-reporting-area-by-zip-code
Retrieve real-time AQI values and categories for a specific reporting area using a Zip code. The tool also fetches nearby area data if no reporting area is associated with the provided Zip code. Supports multiple formats for data output.
Instructions
Get current AQI values and categories for a reporting area by Zip code.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| distance | No | If no reporting area is associated with the Zip code, current 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 | |
| zipCode | Yes | Zip code to get the current observations for. Example: 94954 |
Implementation Reference
- The handler function that executes the tool logic by calling the AirNow API helper and formatting the response.async (params) => { const result = await airnowApi.fetchCurrentObservationsByReportingAreaByZipCode( params ); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch current observations data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; }
- Zod schema defining the input parameters: zipCode (required), format (enum), distance (optional).{ zipCode: z .string() .describe( "Zip code to get the current observations for. Example: 94954" ), 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 Zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150" ), },
- Primary registration of the tool with MCP server, including name, description, schema, and handler.export const registerCurrentObservationsByZipCode = (server: McpServer): void => { server.tool( "get-current-observations-by-reporting-area-by-zip-code", "Get current AQI values and categories for a reporting area by Zip code.", { zipCode: z .string() .describe( "Zip code to get the current observations for. Example: 94954" ), 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 Zip code, current observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150" ), }, async (params) => { const result = await airnowApi.fetchCurrentObservationsByReportingAreaByZipCode( params ); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch current observations data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; } ); };
- src/airnow-api.ts:42-50 (helper)API helper function that constructs the AirNow API request for current observations by zip code and fetches the data.export async function fetchCurrentObservationsByReportingAreaByZipCode(params: Record<string, string>): Promise<string | null> { const endpoint = 'aq/observation/zipcode/current/'; const queryParams = new URLSearchParams(); queryParams.append('zipCode', params.zipCode); queryParams.append('format', params.format); if (params.distance) queryParams.append('distance', params.distance); return airnowGet(endpoint, queryParams); }
- src/tools/index.ts:5-17 (registration)Secondary registration: import and invocation of the tool registrar within the tools index.import { registerCurrentObservationsByZipCode } from "./current-observations-by-reporting-area-by-zip-code.js"; import { registerCurrentObservationsByLatLong } from "./current-observations-by-reporting-area-by-lat-long.js"; import { registerForecastByLatLong } from "./forecast-by-lat-long.js"; import { registerForecastByZipCode } from "./forecast-by-zip-code.js"; import { registerHistoricalObservationsByLatLong } from "./historical-observations-by-reporting-area-by-lat-long.js"; import { registerHistoricalObservationsByZipCode } from "./historical-observations-by-reporting-area-by-zip-code.js"; import { registerObservationsByBoundingBox } from "./observations-by-monitoring-site-by-geographic-bounding-box.js"; export const registerTools = (server: McpServer): void => { registerContourMapsByBoundingBoxCombined(server); registerContourMapsByBoundingBoxOzone(server); registerContourMapsByBoundingBoxPM25(server); registerCurrentObservationsByZipCode(server);