get_nearest_species_observations
Find recent bird sightings near a location using eBird data to locate species observations within a specified distance and timeframe.
Instructions
Find the nearest locations where a species has been seen recently.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude | |
| lng | Yes | Longitude | |
| species_code | Yes | eBird species code | |
| back | No | Number of days back to fetch | |
| hotspot | No | Only fetch from hotspots | |
| include_provisional | No | Include unreviewed observations | |
| max_results | No | Maximum observations to return | |
| dist | No | Maximum distance in km | |
| spp_locale | No | Language for common names | en |
Implementation Reference
- src/index.ts:204-218 (handler)Handler function constructs parameters and calls makeRequest to the eBird /data/nearest/geo/recent/{species_code} endpoint, returning JSON response.
async (args) => { const params: Record<string, string | number | boolean> = { lat: args.lat, lng: args.lng, back: args.back, hotspot: args.hotspot, includeProvisional: args.include_provisional, maxResults: args.max_results, sppLocale: args.spp_locale, }; if (args.dist) params.dist = args.dist; const result = await makeRequest(`/data/nearest/geo/recent/${args.species_code}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } - src/index.ts:193-202 (schema)Zod schema defining input parameters for the tool with descriptions, defaults, and constraints.
{ lat: z.number().min(-90).max(90).describe("Latitude"), lng: z.number().min(-180).max(180).describe("Longitude"), species_code: z.string().describe("eBird species code"), back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"), 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(3000).default(3000).describe("Maximum observations to return"), dist: z.number().min(0).max(50).optional().describe("Maximum distance in km"), spp_locale: z.string().default("en").describe("Language for common names"), - src/index.ts:190-219 (registration)MCP server.tool registration defining the tool name, description, input schema, and handler function.
server.tool( "get_nearest_species_observations", "Find the nearest locations where a species has been seen recently.", { lat: z.number().min(-90).max(90).describe("Latitude"), lng: z.number().min(-180).max(180).describe("Longitude"), species_code: z.string().describe("eBird species code"), back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"), 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(3000).default(3000).describe("Maximum observations to return"), dist: z.number().min(0).max(50).optional().describe("Maximum distance in km"), spp_locale: z.string().default("en").describe("Language for common names"), }, async (args) => { const params: Record<string, string | number | boolean> = { lat: args.lat, lng: args.lng, back: args.back, hotspot: args.hotspot, includeProvisional: args.include_provisional, maxResults: args.max_results, sppLocale: args.spp_locale, }; if (args.dist) params.dist = args.dist; const result = await makeRequest(`/data/nearest/geo/recent/${args.species_code}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } ); - src/index.ts:19-36 (helper)Shared helper function to make authenticated requests to eBird API v2 endpoints.
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(); }