Weather Service

Last Updated on : 2024-06-05 03:15:11download

API list

Action Description
weather.countryCities Query a list of cities.
weather.city Query information about a city.
weather.positionCities Query city information by longitude and latitude.
weather.forecastCity Query the weather forecast for a city.
weather.forecastPosition Query the weather conditions by longitude and latitude.

Query a list of cities

API description

Get a list of cities supported by all weather data in a country or region that is specified by country code. Currently, only cities in China can be returned.

API endpoint

action: weather.countryCities

Request parameter

Parameter name Type Description Required
country_code String The country code. Yes

Sample request

{
  "action": "weather.countryCities",
  "params": {
        "country_code": "cn"
  }
}

Response parameter

Parameter name Type Description
code Integer The response code. For more information, see Error codes.
success Boolean Indicates whether the operation is successful. Valid values:
  • true: success.
  • false: failure.
  • msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
    result Object The returned result.

    Description of result

    Parameter name Type Description
    area String The name of the area.
    pinyin String The Hanyu Pinyin of the area name in Chinese.
    province String The name of the province.
    city String The name of the city.
    cityId String The city ID.

    Sample response

    {
        "success": true,
        "t": 1541399281296,
        "result": [
            {
                  "area": "Beijing",
                  "pinyin": "beijingshi",
                  "province": "Beijing",
                  "city": "Beijing",
                  "cityId": "793409505965772800"
            },
            {
                  "area": "Tianjin",
                  "pinyin": "tianjinshi",
                  "province": "Tianjin",
                  "city": "Tianjin",
                  "cityId": "793409507844820992"
            }
        ]
    }
    

    Error codes

    The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

    Error code Description
    500 A system error has occurred while processing your request.
    1106 Invalid permission.

    Query information about city

    API description

    Query information about a city by city ID.

    API endpoint

    action: weather.city
    

    Request parameter

    Parameter name Type Description Required
    city_id String The city ID. Yes

    Sample request

    {
      "action": "weather.city",
      "params": {
            "city_id": "793409534348627968"
      }
    }
    

    Response parameter

    Parameter name Type Description
    code Integer The response code. For more information, see Error codes.
    success Boolean Indicates whether the operation is successful. Valid values:
  • true: success.
  • false: failure.
  • msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
    result Object The returned result.

    Description of result

    Parameter name Type Description
    id String The city ID.
    ids String The time when the data was last updated.
    dbTable String The city information.
    parentId Integer The city information.
    name String The name of the city.
    shortName String The city information.
    province String The name of the province.
    countryName String The name of the country or region.
    parentCityName String The city information.
    level Integer The city information.
    lon String The longitude.
    lat String The latitude.
    cityHash String The city information.
    cityIndexId Integer The city information.
    domesticCity Boolean The city information.

    Sample response

    {
        "success": true,
        "t": 1541399281296,
        "result": {
            "id": 793409534348627968,
            "ids": null,
            "gmtCreate": 1477877317000,
            "gmtModified": 1477877317000,
            "dbTable": null,
            "parentId": 793416838972313600,
            "name": "Hangzhou",
            "shortName": "Hangzhou",
            "province": "Zhejiang",
            "countryName": "China",
            "parentCityName": "Hangzhou",
            "level": 3,
            "lon": "120.1650798",
            "lat": "30.25258003",
            "cityHash": "wtmk",
            "cityIndexId": 62160,
            "domesticCity": true
        }
    }
    

    Error codes

    The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

    Error codes Description
    500 A system error has occurred while processing your request.
    1106 Invalid permission.

    Query a list of cities by longitude and latitude

    API description

    Query city information by longitude and latitude.

    API endpoint

    action: weather.positionCities
    

    Request parameter

    Parameter name Type Description Required
    lon String The longitude. Yes
    lat String The latitude. Yes

    Sample request

    {
      "action": "weather.positionCities",
      "params": {
            "lon": "120.165",
            "lat": "30.252"
      }
    }
    

    Response parameter

    Parameter name Type Description
    code Integer The response code. For more information, see Error codes.
    success Boolean Indicates whether the operation is successful. Valid values:
  • true: success.
  • false: failure.
  • msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
    result Object The returned result.

    Description of result

    Parameter name Type Description
    area String The name of the area.
    pinyin String The Hanyu Pinyin of the area name in Chinese.
    province String The name of the province.
    city String The name of the city.
    cityId Integer The city ID.

    Sample response

    {
        "success": true,
        "t": 1541401512639,
        "result": {
            "area": "Shangcheng District",
            "pinyin": "shangshangchengquou",
            "province": "Zhejiang",
            "city": "Hangzhou",
            "cityId": 793409589986070528
        }
    }
    

    Error codes

    The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

    Error code Description
    500 A system error has occurred while processing your request.
    1106 Invalid permission.

    Query weather forecast for city

    API description

    Query the weather forecast by city ID.

    API endpoint

    action: weather.forecastCity
    

    Request parameter

    Parameter name Type Description Required
    city_id String The city ID. Yes

    Sample request

    {
      "action": "weather.forecastCity",
      "params": {
            "city_id": "793409534348627968"
      }
    }
    

    Response parameter

    Parameter name Type Description
    code Integer The response code. For more information, see Error codes.
    success Boolean Indicates whether the operation is successful. Valid values:
  • true: success.
  • false: failure.
  • msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
    result Object The returned result.

    Description of result

    Parameter name Type Description
    year-mouth-day Object The weather forecast for a date.

    Description of weather forecast

    Parameter name Type Description
    condTxt String -
    tempRange String The range of temperature.
    updateTime String The time when the data was last updated.

    Sample request

    {
        "success": true,
        "t": 1541402025275,
        "result": {
            "2018-11-07": {
                "condTxt": "Light rain",
                "tempRange": "16-20",
                "updateTime": null
            },
            "2018-11-08": {
                "condTxt": "Light rain",
                "tempRange": "10-18",
                "updateTime": null
            }
        }
    }
    

    Error codes

    The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

    Error code Description
    500 A system error has occurred while processing your request.
    1106 Invalid permission.

    Query weather conditions by longitude and latitude

    API description

    Query weather conditions in a city by longitude and latitude of the city.

    API endpoint

    action: weather.forecastPosition
    

    Request parameter

    Parameter name Type Description Required
    lon String The longitude. Yes
    lat String The latitude. Yes

    Sample request

    {
      "action": "weather.forecastPosition",
      "params": {
            "lon": "120.1650798",
            "lat": "30.25258003"
      }
    }
    

    Response parameter

    Parameter name Type Description
    code Integer The response code. For more information, see Error codes.
    success Boolean Indicates whether the operation is successful. Valid values:
  • true: success.
  • false: failure.
  • msg String The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
    result Object The returned result.

    Description of result

    Parameter name Type Description
    data Object The city information.
    lastUpdateTime String The time when the data was last updated.

    Description of data

    Parameter name Type Description
    temp String The temperature.
    o3 String The Ozone index.
    windLevel String The wind scale.
    pm10 String The PM10 index.
    uvi String The ultraviolet index.
    pressure String The air pressure.
    windDir String The wind direction.
    co String The carbon monoxide index.
    tips String The weather tips.
    realFeel String The apparent temperature.
    no2 String The nitrogen dioxide index.
    condition String The weather conditions, such as sunny, cloudy, rainy, and snowy.
    pm25 String The PM2.5 index.
    so2 String The sulfur dioxide index.
    aqi String The air quality index.
    humidity String The humidity.
    rank String The air quality rating.
    windSpeed String The air speed.

    Sample response

    {
        "success": true,
        "t": 1541403147707,
        "result": {
            "data": {
                "temp": "21",
                "o3": "13",
                "windLevel": "2",
                "pm10": "53",
                "uvi": "4",
                "pressure": "1020",
                "windDir": "East wind",
                "co": "8",
                "tips": "Today is rainy with a comfortable temperature and brings a pleasant feeling." ,
                "realFeel": "21",
                "no2": "21",
                "condition": "Cloudy",
                "pm25": "46",
                "so2": "4",
                "aqi": "53",
                "humidity": "78",
                "rank": "393/577",
                "windSpeed": "2.45"
            },
            "lastUpdateTime": 1541390400000
        }
    }
    

    Error codes

    The following table lists common error codes for the API calls. For more error codes, see Global Error Codes.

    Error code Description
    500 A system error has occurred while processing your request.
    1106 Invalid permission.