QWeather Getting Started: Quick Integration Guide (2026)

Getting started overview

Integrating with the QWeather API involves a sequence of steps designed to enable developers to access weather data efficiently. This guide outlines the essential procedures for setting up an account, obtaining necessary credentials, and executing a foundational API request. The QWeather platform offers various data types, including real-time weather, forecasts, and historical data, accessible via a RESTful API structure. Developers typically utilize JSON for request and response bodies. The process outlined here focuses on the initial setup required to make a successful API call, providing a practical foundation for further integration into applications.

Before proceeding, ensure you have an active internet connection and a development environment capable of making HTTP requests, such as a command-line tool like curl or a programming language with HTTP client libraries. QWeather provides SDKs for JavaScript, Python, Java, PHP, and Android development, which can simplify API interactions once the initial setup is complete.

Create an account and get keys

To access the QWeather API, you must first register for an account and obtain the necessary API credentials. These credentials typically involve an API Key and a Project Key, which authenticate your requests and link them to your chosen service plan.

1. Register for a QWeather Account: Navigate to the QWeather official website and locate the registration or sign-up option. Provide the required information, such as an email address and password, to create your account.
2. Select a Service Plan: After registration, you will usually be prompted to select a service plan. QWeather offers a Developer Free Plan, which provides up to 1,000 requests per day, suitable for initial testing and development. For higher usage limits or additional features, paid plans are available, starting with the Basic Plan at approximately ¥99/month for 50,000 requests/day.
3. Generate API Key and Project Key: Once your account is active and a plan is selected, log in to the QWeather Developer Platform or console. Within the console, you will find a section for API key management. Create a new project or select an existing one. Typically, this process will generate both an API Key (key) and a Project Key (publicid or similar identifier). The API Key serves as your primary authentication token, while the Project Key might be used for linking requests to specific projects or applications, especially if you manage multiple integrations.

   Important: Treat your API Key as sensitive information. Do not embed it directly into client-side code where it could be publicly exposed. For web applications, API requests should ideally be proxied through a backend server to keep the API Key secure. For mobile or IoT applications, use environment variables or secure storage mechanisms provided by the operating system or application framework.

Your first request

After obtaining your API Key and Project Key, you can make your first API request to retrieve weather data. This example demonstrates how to fetch the current weather for a specific location using the QWeather API. For this example, we will use the Weather Now API endpoint, which provides real-time weather conditions.

API Endpoint Structure

QWeather API requests follow a standard RESTful pattern. The base URL for most API calls is https://api.qweather.com/v7/. Append the specific API path and parameters to this base URL.

A typical request URL for current weather data will look like this:

https://api.qweather.com/v7/weather/now?location={location_id}&key={your_api_key}

Where:

• {location_id}: The ID of the geographical location you want weather data for. You can find location IDs using the QWeather GeoAPI - City Lookup. For example, Beijing's ID is 101010100.
• {your_api_key}: Your unique API Key obtained from the QWeather Developer Platform.

Example: Current Weather for Beijing

Let's retrieve the current weather conditions for Beijing using its location ID 101010100.

curl "https://api.qweather.com/v7/weather/now?location=101010100&key=YOUR_API_KEY"

Replace YOUR_API_KEY with your actual API key. When you execute this curl command, the API will return a JSON response containing the current weather data for Beijing.

Example JSON Response (abbreviated):

{
  "code": "200",
  "updateTime": "2026-05-29T10:30+08:00",
  "fxLink": "http://www.qweather.com/weather/beijing-101010100.html",
  "now": {
    "obsTime": "2026-05-29T10:20+08:00",
    "temp": "25",
    "feelsLike": "26",
    "icon": "100",
    "text": "Sunny",
    "wind360": "120",
    "windDir": "SE",
    "windScale": "2",
    "windSpeed": "9",
    "humidity": "50",
    "precip": "0.0",
    "pressure": "1008",
    "vis": "20",
    "cloud": "0",
    "dew": "14"
  },
  "refer": {
    "sources": [
      "QWeather" 
    ]
  }
}

A "code": "200" in the response indicates a successful request. The "now" object contains the current weather details, such as temperature (temp), weather condition text (text), and humidity (humidity).

Using a Programming Language (Python Example)

For programmatic access, you can use an HTTP client library in your preferred language. Here's a Python example using the requests library:

import requests

api_key = "YOUR_API_KEY"
location_id = "101010100" # Beijing

url = f"https://api.qweather.com/v7/weather/now?location={location_id}&key={api_key}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an exception for HTTP errors
    data = response.json()
    print(data)
    if data.get("code") == "200":
        current_temp = data["now"]["temp"]
        weather_text = data["now"]["text"]
        print(f"Current temperature in Beijing: {current_temp}°C, {weather_text}")
    else:
        print(f"API Error: {data.get('code')}")
except requests.exceptions.HTTPError as errh:
    print(f"Http Error: {errh}")
except requests.exceptions.ConnectionError as errc:
    print(f"Error Connecting: {errc}")
except requests.exceptions.Timeout as errt:
    print(f"Timeout Error: {errt}")
except requests.exceptions.RequestException as err:
    print(f"Something Else: {err}")

This Python script fetches the current weather and prints relevant details. Remember to replace "YOUR_API_KEY" with your actual key.

Common next steps

After successfully making your first API call, consider these next steps to further integrate QWeather into your projects:

1. Explore Additional API Endpoints: QWeather offers a range of API endpoints for various weather data types, including daily forecasts, hourly forecasts, historical weather, air quality, and astronomical data. Consult the QWeather API reference documentation to discover other available services and their parameters.
2. Implement Location Lookup: Instead of hardcoding location IDs, integrate the QWeather GeoAPI to allow users to search for locations dynamically. This API enables you to find location IDs by city name, IP address, or geographical coordinates.
3. Utilize QWeather SDKs: For supported languages like Python, Java, JavaScript, PHP, and Android, consider using the official QWeather SDKs. SDKs often simplify API interactions by handling request signing, response parsing, and error handling, reducing the amount of boilerplate code you need to write.
4. Error Handling and Rate Limits: Implement robust error handling in your application to manage API responses with non-200 status codes or error messages. Also, be mindful of your plan's daily request limits. Implement caching strategies or staggered requests to avoid exceeding these limits, especially in production environments.
5. Secure Your API Key: Ensure your API key is not exposed in client-side code or public repositories. For web applications, proxy API requests through a backend server. For other applications, use environment variables or secure credential management systems. General best practices for API key security are detailed by organizations like the Google Developers documentation on API security, which apply broadly to various API integrations.
6. Monitor API Usage: QWeather provides a developer console where you can monitor your API usage, view request statistics, and manage your projects and keys. Regularly checking this console can help you stay within your plan's limits and diagnose issues.

Troubleshooting the first call

When making your initial QWeather API call, you might encounter issues. Here are common problems and their solutions:

• "code": "400" (Bad Request):

  • Issue: Often indicates missing or invalid parameters.
  • Solution: Double-check the URL and query parameters. Ensure that location and key are present and correctly formatted. Verify the location_id is valid. Consult the QWeather Weather Now API documentation for required parameters.

• "code": "401" (Unauthorized):

  • Issue: Your API key is invalid or not authorized.
  • Solution: Confirm that the API key in your request exactly matches the key generated in your QWeather Developer Platform. Ensure the key is active and not revoked. If you recently changed plans, it might take a moment for the new permissions to propagate.

• "code": "402" (No Rights / Plan Limit Exceeded):

  • Issue: Your current plan does not have access to the requested data, or you have exceeded your daily request limit.
  • Solution: Verify your current QWeather service plan on the pricing page and confirm it includes access to the specific API endpoint you are calling. Check your usage statistics in the developer console to see if you have exceeded your daily request quota. If so, wait until the quota resets or consider upgrading your plan.

• "code": "403" (Forbidden):

  • Issue: Access to the API is denied due to IP restrictions or other security policies.
  • Solution: Review your account settings in the QWeather Developer Platform for any IP whitelist configurations. If your requests are coming from an unlisted IP address, you might need to add it to your allowed list.

• "code": "404" (Not Found):

  • Issue: The requested resource (e.g., location_id) does not exist.
  • Solution: Double-check the location_id for accuracy. Use the QWeather GeoAPI City Lookup to find valid location IDs.

• Network Errors (e.g., connection timed out, DNS resolution failure):

  • Issue: Problems with network connectivity or DNS.
  • Solution: Verify your internet connection. Ensure there are no firewalls or proxy settings blocking access to api.qweather.com. Try pinging api.qweather.com from your terminal to check connectivity.

For persistent issues, consult the QWeather FAQ and developer documentation or contact QWeather support.