get_historic_observations
Retrieve bird observations from a specific historical date using region code, date parameters, and filters for taxonomic categories or hotspot locations.
Instructions
Get observations from a specific date in history.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| region_code | Yes | Country, subnational1, subnational2, or location code | |
| year | Yes | Year | |
| month | Yes | Month | |
| day | Yes | Day of month | |
| cat | No | Taxonomic category filter | |
| detail | No | Level of detail | simple |
| hotspot | No | Only fetch from hotspots | |
| include_provisional | No | Include unreviewed observations | |
| max_results | No | Maximum observations to return | |
| rank | No | 'mrec' for latest, 'create' for first added | mrec |
| spp_locale | No | Language for common names | en |
Implementation Reference
- src/index.ts:267-280 (handler)The handler function that executes the logic for the get_historic_observations tool. It builds query parameters and makes an API request to eBird's historic observations endpoint.async (args) => { const params: Record<string, string | number | boolean> = { detail: args.detail, hotspot: args.hotspot, includeProvisional: args.include_provisional, rank: args.rank, sppLocale: args.spp_locale, }; if (args.cat) params.cat = args.cat; if (args.max_results) params.maxResults = args.max_results; const result = await makeRequest(`/data/obs/${args.region_code}/historic/${args.year}/${args.month}/${args.day}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; }
- src/index.ts:255-266 (schema)Zod schema defining the input parameters and validation for the get_historic_observations tool.region_code: z.string().describe("Country, subnational1, subnational2, or location code"), year: z.number().min(1800).describe("Year"), month: z.number().min(1).max(12).describe("Month"), day: z.number().min(1).max(31).describe("Day of month"), cat: z.string().optional().describe("Taxonomic category filter"), detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail"), hotspot: z.boolean().default(false).describe("Only fetch from hotspots"), include_provisional: z.boolean().default(false).describe("Include unreviewed observations"), max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"), rank: z.enum(["mrec", "create"]).default("mrec").describe("'mrec' for latest, 'create' for first added"), spp_locale: z.string().default("en").describe("Language for common names"), },
- src/index.ts:251-281 (registration)Registration of the get_historic_observations tool on the MCP server using server.tool(), including name, description, schema, and handler function.server.tool( "get_historic_observations", "Get observations from a specific date in history.", { region_code: z.string().describe("Country, subnational1, subnational2, or location code"), year: z.number().min(1800).describe("Year"), month: z.number().min(1).max(12).describe("Month"), day: z.number().min(1).max(31).describe("Day of month"), cat: z.string().optional().describe("Taxonomic category filter"), detail: z.enum(["simple", "full"]).default("simple").describe("Level of detail"), hotspot: z.boolean().default(false).describe("Only fetch from hotspots"), include_provisional: z.boolean().default(false).describe("Include unreviewed observations"), max_results: z.number().min(1).max(10000).optional().describe("Maximum observations to return"), rank: z.enum(["mrec", "create"]).default("mrec").describe("'mrec' for latest, 'create' for first added"), spp_locale: z.string().default("en").describe("Language for common names"), }, async (args) => { const params: Record<string, string | number | boolean> = { detail: args.detail, hotspot: args.hotspot, includeProvisional: args.include_provisional, rank: args.rank, sppLocale: args.spp_locale, }; if (args.cat) params.cat = args.cat; if (args.max_results) params.maxResults = args.max_results; const result = await makeRequest(`/data/obs/${args.region_code}/historic/${args.year}/${args.month}/${args.day}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } );
- src/index.ts:19-36 (helper)Shared helper function used by the tool to make authenticated requests to the eBird API.async function makeRequest(endpoint: string, params: Record<string, string | number | boolean> = {}): Promise<unknown> { const url = new URL(`${BASE_URL}${endpoint}`); Object.entries(params).forEach(([key, value]) => { if (value !== undefined && value !== null) { url.searchParams.append(key, String(value)); } }); const response = await fetch(url.toString(), { headers: { "X-eBirdApiToken": API_KEY! }, }); if (!response.ok) { throw new Error(`eBird API error: ${response.status} ${response.statusText}`); } return response.json(); }