Skip to main content
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:
Then pass the returned id as location to a forecast tool from Forecasts. Always describe_tool before executing — the POI tools require a type, and the city search accepts a country filter via range.
Building with code? The same lookup is available as the fixed-contract weather.location.search Scenario Method, which returns a normalized location page, and pairs with weather.forecast; see Scenario Methods.

​
FAQ

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.
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.
It is reference data — ids, names and coordinates change rarely — and it is fetched from QWeather at request time.