get_hotspots_in_region
Find birding hotspots within a specific region using eBird data. Filter results by recent visitor activity and choose output format.
Instructions
Get birding hotspots in a region.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| region_code | Yes | Country, subnational1, or subnational2 code | |
| back | No | Only hotspots visited in last N days | |
| fmt | No | Response format | json |
Implementation Reference
- src/index.ts:399-414 (registration)Registration of the 'get_hotspots_in_region' tool using server.tool(), including name, description, input schema with Zod validation, and the handler function.
server.tool( "get_hotspots_in_region", "Get birding hotspots in a region.", { region_code: z.string().describe("Country, subnational1, or subnational2 code"), back: z.number().min(1).max(30).optional().describe("Only hotspots visited in last N days"), fmt: z.enum(["json", "csv"]).default("json").describe("Response format"), }, async (args) => { const params: Record<string, string | number | boolean> = { fmt: args.fmt }; if (args.back) params.back = args.back; const result = await makeRequest(`/ref/hotspot/${args.region_code}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } ); - src/index.ts:407-413 (handler)Handler function that prepares query parameters (fmt and optional back) and calls the shared makeRequest helper to fetch hotspot data from the eBird API endpoint `/ref/hotspot/${region_code}`, returning the JSON-stringified result wrapped in MCP content format.
async (args) => { const params: Record<string, string | number | boolean> = { fmt: args.fmt }; if (args.back) params.back = args.back; const result = await makeRequest(`/ref/hotspot/${args.region_code}`, params); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }; } - src/index.ts:402-406 (schema)Input schema defined using Zod for parameter validation: region_code (required string), back (optional number 1-30), fmt (enum json/csv, default json).
{ region_code: z.string().describe("Country, subnational1, or subnational2 code"), back: z.number().min(1).max(30).optional().describe("Only hotspots visited in last N days"), fmt: z.enum(["json", "csv"]).default("json").describe("Response format"), }, - src/index.ts:19-36 (helper)Shared helper function used by all tools to make authenticated HTTP requests to the eBird API, handling URL params, fetch, error checking, and JSON parsing.
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(); }