get_nearby_observations
Find recent bird observations near any location using eBird data. Filter by date range, distance, species category, and hotspots to discover local bird sightings.
Instructions
Get recent observations near a geographic location.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude | |
| lng | Yes | Longitude | |
| back | No | Number of days back to fetch | |
| cat | No | Taxonomic category filter | |
| dist | No | Search radius in kilometers | |
| hotspot | No | Only fetch from hotspots | |
| include_provisional | No | Include unreviewed observations | |
| max_results | No | Maximum observations to return | |
| sort | No | Sort by date or species | date |
| spp_locale | No | Language for common names | en |
Implementation Reference
- src/index.ts:140-156 (handler)The asynchronous handler function that implements the core logic of the 'get_nearby_observations' tool. It constructs query parameters from inputs and calls the eBird API's /data/obs/geo/recent endpoint via makeRequest.async (args) => { const params: Record<string, string | number | boolean> = { lat: args.lat, lng: args.lng, back: args.back, dist: args.dist, hotspot: args.hotspot, includeProvisional: args.include_provisional, sort: args.sort, 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/geo/recent", params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; }
- src/index.ts:128-139 (schema)Zod input schema defining parameters for latitude, longitude, search radius, time frame, filters, and sorting for the get_nearby_observations tool.{ lat: z.number().min(-90).max(90).describe("Latitude"), lng: z.number().min(-180).max(180).describe("Longitude"), back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"), cat: z.string().optional().describe("Taxonomic category filter"), dist: z.number().min(0).max(50).default(25).describe("Search radius in kilometers"), 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"), sort: z.enum(["date", "species"]).default("date").describe("Sort by date or species"), spp_locale: z.string().default("en").describe("Language for common names"), },
- src/index.ts:125-157 (registration)MCP server.tool registration for 'get_nearby_observations', including name, description, schema, and handler.server.tool( "get_nearby_observations", "Get recent observations near a geographic location.", { lat: z.number().min(-90).max(90).describe("Latitude"), lng: z.number().min(-180).max(180).describe("Longitude"), back: z.number().min(1).max(30).default(14).describe("Number of days back to fetch"), cat: z.string().optional().describe("Taxonomic category filter"), dist: z.number().min(0).max(50).default(25).describe("Search radius in kilometers"), 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"), sort: z.enum(["date", "species"]).default("date").describe("Sort by date or species"), 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, dist: args.dist, hotspot: args.hotspot, includeProvisional: args.include_provisional, sort: args.sort, 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/geo/recent", params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } );
- src/index.ts:19-36 (helper)Utility function used by all tools, including get_nearby_observations, to perform authenticated HTTP 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(); }