Geography

The Geography section provides reference endpoints for location lookup and search. Use these endpoints to fetch country lists, country cities, and location slugs for weather requests.

Authentication

All Geography endpoints require an API token:

Header: X-token: TOKEN
Query: ?key=TOKEN (if supported by your client flow)

Endpoints Overview

Endpoint	Method	Purpose
`/v2/geography/countries/`	`GET`	Get all available countries.
`/v2/geography/countries/?country_code={code}`	`GET`	Get a country by ISO code (for example `US`).
`/v2/geography/countries/cities/?country_code={code}`	`GET`	Get cities for a country code.
`/v2/geography/search/?q={query}&limit={n}`	`GET`	Search locations by name.

1. Countries List

Returns all available countries with slug and ISO code.

curl --location 'https://api.meteoflow.com/v2/geography/countries/' \
--header 'X-token: TOKEN'

Response Structure

Field	Description	Format
`country_slug`	Country slug used in API location references.	String
`country_name`	Country display name.	String
`country_code`	ISO 3166-1 alpha-2 country code.	String

2. Country By Code

Filters countries by country_code (case-insensitive).

curl --location 'https://api.meteoflow.com/v2/geography/countries/?country_code=us' \
--header 'X-token: TOKEN'

Example result:

[
  {
    "country_slug": "united-states",
    "country_name": "United States",
    "country_code": "US"
  }
]

3. Cities By Country

Returns all indexed cities for a specific country.

curl --location 'https://api.meteoflow.com/v2/geography/countries/cities/?country_code=us' \
--header 'X-token: TOKEN'

Response Structure

Field	Description	Format
`country`	Country code.	String
`slug`	Location slug for weather endpoints.	String
`timezone_offset`	UTC offset in minutes.	Number
`latitude`	Latitude.	Number
`longitude`	Longitude.	Number
`city_name`	City name.	String
`country_name`	Country name.	String
`region_name`	Region/state name.	String

4. Location Search

Searches locations by free-text query.

curl --location 'https://api.meteoflow.com/v2/geography/search/?q=london&limit=10' \
--header 'X-token: TOKEN'

Query Parameters

Parameter	Required	Description
`q`	Yes	Search string (for example city name).
`limit`	No	Max number of results to return.

Response Structure

Field	Description	Format
`country`	Country code.	String
`slug`	Location slug for weather endpoints.	String
`timezone_offset`	UTC offset in minutes.	Number
`latitude`	Latitude.	Number
`longitude`	Longitude.	Number
`city_name`	City name.	String
`country_name`	Country name.	String
`region_name`	Region/state name.	String

Use the slug returned by Geography in weather endpoints such as /v2/current/ and /v2/forecast/....

Air Quality

For Developers

Explore available API endpoints for weather and geography data.