Recipe: Location Search
Most AccuWeather weather endpoints (current conditions, forecasts, alerts, etc.) require a LocationKey — a unique numeric identifier for a specific location. This recipe shows you how to look up that key before making your first weather request.
These recipes are teaching examples — not production code.
- Host: examples use the development host apidev.accuweather.com. Switch to api.accuweather.com for production.
- Production hardening: GZIP compression, caching, retries with exponential backoff, and error handling are not included. See the Best Practices guide.
Scenario
"I want to display weather for New York City. How do I get the LocationKey I need?"
Call the city search endpoint with a text query. The API returns an array of matching locations ranked by relevance.
Endpoint:
Code
Key response fields
| Field | Type | Description |
|---|---|---|
Key | String | The LocationKey — save this for all weather requests |
LocalizedName | String | Human-readable city name |
Country.ID | String | ISO 3166-1 alpha-2 country code |
AdministrativeArea.ID | String | State/province/region code |
Rank | Integer | Lower = more prominent location (1–500+) |
DataSets | Array | Which APIs are available for this location |
GeoPosition | Object | Latitude, longitude, and elevation |
Alternative search methods
By postal code:
Code
By coordinates (lat/lon):
Code
Autocomplete (for search-as-you-type UIs):
Code
Common pitfalls
Too many results? Add the countryCode parameter to narrow results to a specific country:
Code
DataSets matters — if MinuteCast or Alerts is not in the DataSets array, those APIs won't return data for this location.
Complete code sample
Copy a full, runnable example that searches for a location and extracts its LocationKey.
Next steps
With your LocationKey in hand, continue to:
- Current Conditions — get real-time weather right now
- Hourly Forecast — hour-by-hour precipitation and temperature
- 5-Day Daily Forecast — daily highs, lows, and conditions