> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentkey.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Weather location lookup for AI agents

> Turn a place name or coordinate into a QWeather location id — city search, reverse lookup, POI and range search, top cities — the step before any forecast.

Weather data is attached to places, and QWeather identifies places by a
location id. Before an agent can fetch a forecast it has to turn "Hangzhou",
"the station near West Lake" or a pair of coordinates into that id — or
confirm which of several same-named towns the user meant. Through AgentKey
this lookup is one step with the same three calls — `find_tools`,
`describe_tool`, `execute_tool` — and it doubles as a small gazetteer: names
in many languages, timezone, elevation and administrative parents.

## What you can ask

* *"What's the location id for Hangzhou?"*
* *"Which city is at longitude 116.41, latitude 39.92?"*
* *"Find every place called Springfield in the United States."*
* *"深圳的 Location ID 是什么？"*
* *"List the scenic spots around West Lake."*
* *"Which tide stations are within 20 km of this coordinate?"*
* *"Give me the top ten cities in Japan for a weather picker."*
* *"Return this city's name in English and Chinese, with its timezone and elevation."*

## What's covered

**City search**

* Search by name, including fuzzy matches from one or two characters, or
  reverse-lookup from a `longitude,latitude` pair
* Narrow by parent administrative region or by country; choose how many
  results to return
* Each match carries its location id, names in multiple languages, latitude
  and longitude, timezone, elevation, a rank, and its parent administrative
  regions

**Points of interest**

* POI search by keyword and coordinates — scenic spots, stations, airports,
  ports and similar — filtered by POI type
* Range search for every POI of a type within a radius of a coordinate, from
  one to fifty kilometres
* The tide-station types used by the tide tool are among the POI types

**Top cities**

* The popular cities of a country, with a configurable count

**Why it comes first**

* Current weather, hourly and daily forecasts, indices and the minute-level
  rain tool all take a location id or coordinates; the id from this lookup is
  what you pass to them

## How to use it

Pass the request in plain language and let the router pick the tool:

```text theme={null}
find_tools(q="location id for Hangzhou")
find_tools(q="深圳的 Location ID")
find_tools(prefix="weather/qweather")      # browse all weather tools
describe_tool("<returned Provider/Operation>")
execute_tool("<Provider/Operation>", { location: "Hangzhou" })
```

Then pass the returned id as `location` to a forecast tool from
[Forecasts](/capabilities/weather/forecasts). Always `describe_tool` before
executing — the POI tools require a `type`, and the city search accepts a
country filter via `range`.

> [!NOTE]
>
> **Building with code?** The same lookup is available as the fixed-contract
> [`weather.location.search`](/api-reference/scenario/methods/weather-location-search)
> Scenario Method, which returns a normalized location page, and pairs with
> [`weather.forecast`](/api-reference/scenario/methods/weather-forecast); see
> [Scenario Methods](/api-reference/scenario/overview).

## FAQ

> **Which languages can names be returned in?**
>
> The lookup is multilingual: pass `lang` to get names in the language you
> need, and query in Chinese or English. Each result also carries names in
> several languages.

> **Can I skip the lookup and pass coordinates?**
>
> Often, yes. City tools accept a `longitude,latitude` pair in place of an
> id, grid tools take coordinates only, and air-quality and alert tools
> take `latitude` and `longitude`. The lookup is still the way to confirm
> which place a name refers to.

> **How fresh is this data?**
>
> It is reference data — ids, names and coordinates change rarely — and it
> is fetched from QWeather at request time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.