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();
}

eBird MCP Server