canonical: https://jentic.com/apis/groundhog-day.com/groundhog-day

# Groundhog Day API

The Groundhog Day API exposes structured data on every prognosticating animal across North America and their annual Groundhog Day weather predictions. The dataset covers around 70 groundhogs and other forecasting critters from the United States and Canada, going back to 1886 for animals like Punxsutawney Phil. Endpoints return groundhog profiles, individual prediction records, and yearly prediction batches filtered by year, country, or species type. The API is open and unauthenticated, making it useful for trivia bots, news-room automation around February 2nd, and educational data projects.

## For AI agents

Look up groundhogs and Groundhog Day weather predictions from across North America by name, country, or year. No authentication required.

## Scope

Does not handle real-time meteorological forecasts, climate modelling, or Groundhog Day ceremony scheduling - use for North American groundhog prediction lookups only.

## Capabilities

- Retrieve a list of every prognosticating animal on file with profile metadata, region, and historical prediction counts
- Fetch a single groundhog by slug (for example punxsutawney-phil or wiarton-willie) including its full prediction history
- Filter groundhogs by country to compare US versus Canadian prognosticators in one call
- Distinguish actual groundhogs from other forecasting species using the isGroundhog flag at query time
- Pull every recorded prediction for a given calendar year between 1886 and the current Groundhog Day
- Generate Groundhog Day news copy and social posts driven by live shadow or no-shadow data each February

## Use cases

### Newsroom Groundhog Day coverage

Power Groundhog Day news cards, tickers, and morning-show graphics with live data on every prognosticating animal across North America. Editorial teams hit a single endpoint on February 2nd to pull each groundhog's shadow result, location, and historical accuracy without scraping individual ceremony pages. The dataset covers about 70 prognosticators going back to 1886 and is free to use without an API key.

Example prompt: Call GET `/api/v1/predictions`?year=2024 and produce a ranked list of which prognosticators saw their shadow versus predicted an early spring.

### Trivia and chatbot answers

Answer ad-hoc trivia questions about Groundhog Day prognosticators inside chatbots, voice assistants, and Slack apps. The API returns structured profiles for each animal including name, city, region, country, species type and full prediction history, so a bot can answer 'how many times has Phil seen his shadow?' or 'which Canadian groundhog predicted an early spring last year?' without static data. No authentication is needed, which keeps integration to a single HTTP call.

Example prompt: Call GET `/api/v1/groundhogs/punxsutawney-phil` and answer how many times Phil has seen his shadow over his recorded predictions.

### Data journalism and analysis projects

Source clean structured Groundhog Day prediction data for charts, dashboards, and data-journalism stories. The API aggregates predictions from 1886 onwards across roughly 70 animals split between the US and Canada, exposing shadow flags and detail strings that can be piped into Pandas, BigQuery, or a notebook in seconds. Results include geographic metadata so analysts can map prognosticators by region or compare accuracy versus official NOAA winter outcomes.

Example prompt: Fetch all groundhogs via GET `/api/v1/groundhogs`?country=Canada and compute the share that predicted an early spring in 2023.

### AI agent integration through Jentic

Expose the Groundhog Day API as an agent tool through Jentic so language-model agents can answer Groundhog Day questions during their reasoning. The agent searches Jentic for an intent like get the latest groundhog prediction, loads the matching operation schema, and executes the GET `/api/v1/predictions` call without the developer hand-writing any HTTP client code. Because the API requires no auth, the only setup step is the Jentic search-load-execute call.

Example prompt: Through Jentic, search for 'get groundhog day prediction', load the predictions operation, and execute it for the current year.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/groundhogs` | List every prognosticating animal with predictions |
| GET | `/api/v1/groundhogs/{slug}` | Get a single groundhog and its prediction history |
| GET | `/api/v1/predictions` | Get all predictions for a given calendar year |
| GET | `/api/v1/spec` | Download the OpenAPI/YAML schema |
| GET | `/api/v1` | Root welcome endpoint with HATEOAS links |

## Key resources

- **groundhogs** — Profile records for every prognosticating animal including slug, name, city, region, country, species type, and full prediction history
- **predictions** — Annual shadow or no-shadow predictions tied back to the issuing groundhog, queryable by year
- **info** — Service root and downloadable spec endpoint for clients that want to introspect the API

## Why Jentic

- **Setup:** The Groundhog forecast API needs no vendor credentials, but wiring it by hand still means coding the prediction and groundhog-lookup paths and handling retries yourself. Through Jentic you install once, import the Groundhog forecast API from the API Directory, and your agent calls it with no secret to manage.
- **Permission scoping:** The Groundhog forecast API puts the groundhog slug in the URL path (`/api/v1/groundhogs/{slug}`), so a rule can pin your agent to one groundhog or to reads only. You choose the operations it may call, and since every endpoint here is a read, the agent only fetches the predictions and lists you allow.
- **Credential handling:** The Groundhog forecast API requires no vendor credential, so there is nothing to store or rotate. Your agent reaches it only through your own Jentic One instance, which handles routing and retries without exposing any secret in the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the latest groundhog prediction' or 'list groundhogs by country', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenWeather API** — Real meteorological forecasts to compare against groundhog predictions
- **WeatherAPI** — General-purpose weather forecast API if folklore data is not needed
- **NASA Astronomy Picture of the Day** — Another free, no-auth public dataset useful for content and chatbot demos

## FAQ

### What authentication does the Groundhog Day API use?

The Groundhog Day API is open and requires no authentication or API key. Agents can call GET `/api/v1/groundhogs` and GET `/api/v1/predictions` directly. When routed through Jentic the call still requires no vendor credentials, only a Jentic agent key (ak_*) for the Jentic platform itself.

### Can I get every groundhog and its prediction history in one call?

Yes. GET `/api/v1/groundhogs` returns the full list of prognosticators with embedded prediction arrays, and supports country and isGroundhog query filters so you can narrow down to Canadian animals or non-groundhog species without a second request.

### What years of Groundhog Day predictions does this API cover?

The dataset starts in 1886 with Punxsutawney Phil and runs through the most recent Groundhog Day. The `/api/v1/predictions` endpoint validates a year query parameter and rejects anything below 1886, so older years return a 400 error rather than empty data.

### Are there rate limits on the Groundhog Day API?

The published spec does not document hard rate limits. The API is hosted as a free public service, so treat it accordingly: cache results, batch requests where possible, and avoid hammering it during the February 2nd traffic spike.

### How do I look up a single groundhog through Jentic?

Install Jentic with pip install jentic, then run a search for 'get a groundhog by slug', load the matching operation, and execute it with the slug parameter (for example punxsutawney-phil). Jentic handles the request to GET `/api/v1/groundhogs/{slug}` and returns the parsed groundhog object.

### Is the Groundhog Day API free?

Yes. It is a free community API maintained at groundhog-day.com with no paid tier or API key requirement, which is why it is well suited to demos, hackathons, and lightweight agent integrations.

### Can I limit what my agent is allowed to do with the Groundhog Day API?

Yes. Because you run Jentic One yourself, your own rules decide which of this API's operations the agent may call, and every endpoint here is a read (GET `/api/v1/groundhogs`, GET `/api/v1/groundhogs/{slug}`, and GET `/api/v1/predictions`), so the agent can only fetch the lists and predictions you allow. Since the groundhog slug sits in the URL path, a rule can pin the agent to a single groundhog such as punxsutawney-phil or restrict it to prediction lookups only. The API needs no vendor credential, so there is nothing for the agent to store or send beyond the calls you permit.