Tổng quan

API Thoitiet cung cấp các dịch vụ Web API tốc độ cao, hỗ trợ lấy thông tin thời tiết hiện tại và dự báo thời tiết 5 ngày cho 34 tỉnh thành Việt Nam.

Toàn bộ phản hồi dữ liệu API được định dạng dưới dạng JSON. Hệ thống hỗ trợ cập nhật dữ liệu tự động định kỳ từ trạm khí tượng quốc tế hoặc thay đổi linh hoạt thông qua bảng quản trị.

Xác thực (Authentication)

Để truy cập các API thời tiết, bạn cần có một API Key hợp lệ. Hệ thống hỗ trợ truyền API Key qua hai phương thức sau:

Phương thức	Tham số/Tên Header	Ví dụ
HTTP Header (Khuyên dùng)	`X-API-Key`	`X-API-Key: wt_demo_key_2026`
Query Parameter	`apikey`	`https://apithoitiet.thuc.me/api/weather/ha-noi?apikey=wt_demo_key_2026`

API Key dùng thử mặc định: wt_demo_key_2026

Được cung cấp sẵn để bạn phát triển và test ứng dụng.

Tự động lấy API Key cá nhân

Bạn có thể tạo một API Key riêng miễn phí hoạt động ngay lập tức mà không cần đăng ký tài khoản.

Các Endpoints API

GET

Lấy danh sách tỉnh thành

Trả về danh sách 34 tỉnh/thành phố ở Việt Nam kèm toạ độ địa lý và mã viết tắt.

GET /api/provinces

GET

Lấy thời tiết hiện tại

Trả về thông tin thời tiết hiện tại chi tiết của tỉnh/thành phố tương ứng theo slug hoặc code.

GET /api/weather/{province_slug_or_code}

Ví dụ: /api/weather/ha-noi hoặc /api/weather/HCM

GET

Lấy dự báo thời tiết 5 ngày

Trả về dữ liệu dự báo thời tiết cho 5 ngày tiếp theo của tỉnh thành tương ứng.

GET /api/weather/{province_slug_or_code}/forecast

GET

Lấy danh sách xã/phường/thị trấn

Trả về danh sách tất cả các đơn vị hành chính xã/phường/thị trấn trực thuộc tỉnh/thành phố tương ứng.

GET /api/provinces/{province_slug_or_code}/wards

Ví dụ: /api/provinces/ha-noi/wards hoặc /api/provinces/HCM/wards

Code Ví dụ Tích hợp

Terminal cURL

curl -X GET "http://localhost/api/weather/ha-noi" \
  -H "X-API-Key: wt_demo_key_2026"

JS Axios

axios.get('http://localhost/api/weather/ha-noi', {
  headers: {
    'X-API-Key': 'wt_demo_key_2026'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

PHP cURL

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "http://localhost/api/weather/ha-noi");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: wt_demo_key_2026"
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);
?>

Python Requests

import requests

url = "http://localhost/api/weather/ha-noi"
headers = {
    "X-API-Key": "wt_demo_key_2026"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)

API Sandbox (Trình chơi thử)

Hãy chọn các tham số bên dưới để test gọi API thời tiết thực tế trực tiếp từ trình duyệt của bạn.

Tỉnh thành

API Key

Endpoint

Request URL: /api/weather/ha-noi

Response JSON Output: HTTP 200 OK

Bấm "Send Request" để hiển thị dữ liệu JSON...

Mục lục