WhatsMy.Zone Climate Lookup API

Coordinate-based global hardiness zone and frost-date API for horticulture, agtech, and plant-commerce. A successful lookup returns a USDA-style hardiness zone, 30-year average annual extreme minimum temperature, last spring freeze, first autumn freeze, frost-safe season length, frost-regime classifications, and source metadata.

The current public response contract is API version 5.0. It uses Global Hardiness & Freeze-Safe Data for 1996-2025, last updated 2026-04-28.

Use Cases

The API is designed for plant-care applications, nursery tools, e-commerce garden stores, landscape planning, localized growing guides, planting-window recommendations, and weather-aware shipping decisions for freeze-sensitive products like plants, food, cosmetics, chemicals, medications, and other products.

Choose an Access Path

For direct WhatsMy.Zone access, create or sign in to an account at the Account Dashboard. The dashboard lets you create API keys, review usage, choose a plan, and add allowed-domain or allowed-IP restrictions. Copy the generated key and send it in the x-api-key request header.

If you already use RapidAPI, you can subscribe through the RapidAPI marketplace listing instead. RapidAPI uses its own X-RapidAPI-Key header and gateway endpoint, so you do not need a direct WhatsMy.Zone API key for RapidAPI calls.

Getting Coordinates

The lookup requires decimal latitude and longitude. For most integrations, geocode the customer's city, postal code, address, store location, farm, or shipping destination before calling the API. Common sources include your existing checkout/shipping address data, a maps or geocoding provider, GPS coordinates from a mobile app, or coordinates copied from a mapping tool.

Use enough precision for the decision you are making. City or postal-code centroids are usually enough for broad zone and freeze-window estimates. Address-level or GPS coordinates are better for local shipping-risk checks, farms, nurseries, or customers near mountains, coasts, valleys, or zone boundaries. For privacy, avoid storing full addresses if your integration only needs coordinates.

Endpoint

Authentication

Direct production requests to https://whatsmy.zone/api/api-zone.php must pass a WhatsMy.Zone API key in the x-api-key request header. Get that key from the Account Dashboard. URL credential parameters are retired and rejected because URLs can appear in logs, analytics, and browser history.

A small anonymous allowance may be available for evaluation: up to 10 lookups per IP per week with a slower throttle. It is not a production plan. Third-party browser integrations must use a restricted API key.

Marketplace Access

The API is also available through the RapidAPI marketplace. RapidAPI subscribers authenticate with RapidAPI's standard X-RapidAPI-Key header and use the RapidAPI gateway endpoint /rapidapi-zone.php. Do not send a direct WhatsMy.Zone API key to the RapidAPI endpoint.

RapidAPI plans mirror the public self-service quotas: BASIC includes 100 requests per month, PRO includes 1,100, ULTRA includes 2,500, and MEGA includes 15,000. Higher-volume, dedicated infrastructure, custom rate-limit, or negotiated service-term requests should use the contact page.

Browser & Server Security

• Browser apps and widgets — Add allowed domains for any site where your key is embedded. Enter the complete website origin, such as https://example.com. HTTP and HTTPS are treated as separate origins. Widget embed keys remain visible to the embedding page by design, so domain restrictions are required.
• Server-to-server calls — Use the x-api-key header from your backend. If you set allowed IPs, requests without a browser origin must come from one of those IP addresses.
• URL key parameters — Credentials in URL query parameters are rejected because URLs can appear in logs, analytics, and browser history. Send API keys only with the x-api-key header.
• Map tiles — Tile files are protected from direct hotlinking. Use the official widgets for embedded maps; they request signed tile access for authorized domains automatically.

Quickstart

First create or copy a direct API key in the Account Dashboard. Then replace YOUR_API_KEY with that value before running these examples. Do not include the key in the URL.

cURL

JavaScript

Python

Request Parameters

Response Format

A successful land lookup returns a JSON object like this. Freeze-day values are day-of-year numbers. Anonymous-only fields such as anonymous and calls_remaining are omitted when a valid API key is used.

Conservative Frost-Safe Window

The seasonal frost dates are designed as a safer planning guide rather than a risky average. last_freeze_day uses the 90th percentile of annual last spring-freeze dates, while first_freeze_day uses the 10th percentile of annual first autumn-freeze dates. The safe_days value is the window between those two conservative boundaries.

In practical terms, the spring boundary is later than a typical last-freeze date and the autumn boundary is earlier than a typical first-freeze date. This intentionally leaves a safety margin for planning sensitive plantings, harvests, and shipments. It reduces risk but is not a local forecast or a guarantee against unusual weather or microclimate effects.

Response Fields

• api_version — API response version, currently 5.0.
• lat / lon — The returned coordinate values used for the lookup.
• temp_f — 30-year average annual extreme minimum temperature in Fahrenheit, rounded to one decimal place.
• zone — USDA-style hardiness zone calculated from temp_f.
• source — Data provider, dataset, standard, year range, and last update metadata.
• last_freeze_day / first_freeze_day — Conservative 90th-percentile spring and 10th-percentile autumn freeze boundaries as day-of-year values for seasonal climates.
• safe_days — Number of frost-safe growing days between the last spring freeze and first autumn freeze.
• frost_regime — Overall frost classification such as seasonal, tropical, permafrost, irregular, or occasional.
• anonymous / calls_remaining — Returned only for anonymous requests to show free-call status.

Status Codes & Errors

Usage Limits

Authenticated keys default to a minimum interval of one second between requests from the same device unless a custom key setting applies. Current own-domain plans are Free with 100 API calls per month, Starter with 1,100 calls, Growth with 2,500 calls, Business with 15,000 calls, and Enterprise with negotiated limits. Check the Account Dashboard for current pricing, usage, and key-specific restrictions. RapidAPI marketplace plans are billed and enforced by RapidAPI, with the same public monthly quota levels.

Machine-Readable Contract

The canonical OpenAPI 3.1 specification is published at a stable URL for API tools, documentation imports, and directory listings. Its URL remains stable while the info.version field records the response contract version.

A RapidAPI-specific OpenAPI 3.0 specification is also published for the marketplace gateway endpoint. It describes RapidAPI authentication and /rapidapi-zone.php; the canonical direct API contract remains /openapi.yaml.

Versioning & Changelog

Current contract: 5.0. Backward-compatible documentation additions and clarifications retain the current response version. Breaking request or response changes require a documented migration path and an updated contract version.

• 2026-06-04 — Published the RapidAPI marketplace listing with a dedicated gateway endpoint and RapidAPI-specific OpenAPI import file.
• 2026-06-02 — Published the canonical OpenAPI 3.1 contract and expanded developer quickstarts.
• 2026-06-01 — Completed header-only credential transport. Retired URL API key parameters now return 400 Bad Request.
• 2026-04-28 — Updated Global Hardiness & Freeze-Safe Data for the 1996-2025 climate period.

Support & Policies

For integration questions, contact [email protected] or use the contact page. Use of the API is governed by the Terms & Conditions and Privacy Policy. Review the methodology page before using climate results in customer-facing recommendations.