AirGradient API

AirGradient cung cấp các API (giao diện lập trình ứng dụng). Về cơ bản, API là một cầu nối cho phép các hệ thống phần mềm khác nhau giao tiếp với nhau. Trong trường hợp này, API cho phép bạn lấy dữ liệu từ các máy đo AirGradient của mình vào những ứng dụng, trang web hoặc bảng điều khiển dữ liệu của riêng bạn—giúp dữ liệu trở nên hữu ích và dễ tiếp cận hơn cho các nhu cầu cụ thể của bạn. Tài liệu này dành cho các lập trình viên phần mềm và chỉ là một bước không bắt buộc. Việc sử dụng API là tùy chọn để truy cập dữ liệu chất lượng không khí của bạn. Có thể xem phần O6: Tải xuống và Xuất Dữ liệu để biết các cách dễ tiếp cận hơn nhằm truy cập và tải xuống dữ liệu cho những người không phải là lập trình viên.

AirGradient hỗ trợ hai loại API: API Công khai (Public API) cho dữ liệu được lưu trữ trên đám mây AirGradient và API Cục bộ (Local API) để truy cập dữ liệu trực tiếp từ thiết bị qua mạng cục bộ. Điều này mang lại sự linh hoạt cho người dùng tùy thuộc vào việc họ muốn sử dụng các giải pháp dựa trên đám mây hay ưu tiên truy cập cục bộ vì lý do riêng tư hoặc sử dụng ngoại tuyến.

Trong tài liệu này, chúng tôi sẽ trình bày những kiến thức cơ bản về API của AirGradient. Xin lưu ý rằng chúng tôi sẽ không đi sâu vào chi tiết triển khai nâng cao, và bạn có thể cần đến một lập trình viên có kinh nghiệm kỹ thuật để tận dụng tối đa các API.

1. Tại sao nên sử dụng API?

Sử dụng API AirGradient có thể giúp bạn chia sẻ dữ liệu chất lượng không khí một cách hiệu quả với cộng đồng của mình. Nó cho phép bạn tự động đưa các chỉ số chất lượng không khí nội vùng chi tiết của mình lên các trang web, ứng dụng hoặc hệ thống cảnh báo mà không cần liên tục tải xuống dữ liệu thủ công. Điều này làm cho những gì vô hình trở nên hữu hình, cung cấp thông tin kịp thời cho người dân và có được bằng chứng xác thực để vận động và yêu cầu thay đổi.

Dưới đây là một số cách bạn có thể muốn sử dụng API:

• Cảnh báo Sức khỏe Cục bộ hóa: Các hệ thống cảnh báo đơn giản (tin nhắn SMS, thông báo ứng dụng) cảnh báo người dân, trường học hoặc phòng khám về các đợt tăng đột biến chất lượng không khí kém được phát hiện bởi các máy đo gần đó.
• Công cụ Vận động Cộng đồng: Tự động đưa dữ liệu từ máy đo cục bộ vào các bảng điều khiển trực tuyến hoặc báo cáo được chia sẻ với các nhà hoạch định chính sách, cơ quan quản lý và các hãng tin tức để làm nổi bật những điểm nóng ô nhiễm và yêu cầu hành động.
• Bảng Thông tin cho Người thuê/Cư dân: Hiển thị các chỉ số chất lượng không khí cục bộ theo thời gian thực tại các trung tâm cộng đồng, thư viện hoặc sảnh tòa nhà chung cư.
• Công cụ Lập kế hoạch “Tuyến đường An toàn” để Đi bộ/Đi xe đạp: Đề xuất các tuyến đường để tránh các khu vực hiện đang có mức ô nhiễm cao hơn dựa trên các máy đo của cộng đồng.
• Tương quan Ô nhiễm với các Hoạt động Địa phương: Cho phép người dân xem liệu mức độ ô nhiễm (từ máy đo của họ) có tăng lên trong các sự kiện như giờ cao điểm giao thông, hoạt động công nghiệp gần đó hoặc các điều kiện thời tiết cụ thể hay không.
• Bằng chứng cho các Đơn xin Tài trợ: Sử dụng dữ liệu lịch sử dễ dàng truy cập, được sắp xếp từ API để chứng minh sự cần thiết của việc tài trợ cho máy lọc không khí, không gian xanh hoặc các chương trình y tế.
• Trưng bày mang tính giáo dục tại trường học: Hiển thị dữ liệu thời gian thực của học sinh từ một máy đo có thể được đặt ngay trong khuôn viên trường học của các em, qua đó kết nối khoa học môi trường với môi trường xung quanh trực tiếp của các bé.

2. Các tính năng của API AirGradient

Tài liệu về API có thể được tìm thấy trên Swagger. Ở cấp độ cơ bản, API sẽ cho phép bạn lấy thông tin về mọi chỉ số mà máy đo đo được, nghĩa là bạn có thể lấy thông tin PM_2.5, nhiệt độ, hoặc thậm chí là carbon dioxide từ các máy đo AirGradient của mình.

Ngoài ra, bạn cũng có thể lấy dữ liệu từ bất kỳ máy đo AirGradient ngoài trời nào trên toàn thế giới, miễn là nó được đặt ở chế độ xem công khai. Điều này có nghĩa là bạn không chỉ có thể lấy dữ liệu từ các máy đo của riêng mình bằng phương pháp này, mà còn từ hàng ngàn máy đo khác trên toàn cầu. Quan trọng là, bạn cũng có thể lấy dữ liệu lịch sử giới hạn từ bất kỳ máy đo nào trong số này thông qua ID vị trí.

3. Sử dụng API công khai của AirGradient

Để xuất dữ liệu bằng API, hãy làm theo các bước sau:

1. Nhận Mã Token API: Trong bảng điều khiển AirGradient của bạn, đi tới trang Cài đặt Chung (General Settings) dưới thẻ Kết nối. Kích hoạt quyền truy cập API và sau khi thành công, bạn sẽ nhận được một mã token API duy nhất.
   

   

2. Khám phá các Điểm cuối (Endpoints) API Công khai: Bạn có thể tìm thấy tất cả các điểm cuối API công khai có sẵn trong Tài liệu Swagger. Trang này cho phép bạn thử nghiệm các điểm cuối cần thiết và cung cấp mô tả cho từng điểm cuối, bao gồm các tham số bắt buộc.
   

   

3. Xác định ID Vị trí: Một số điểm cuối yêu cầu ID vị trí. Đó là ID duy nhất của vị trí mà máy đo của bạn được liên kết tới. Đây không phải là tên của vị trí. Để tìm nó, hãy truy cập trang Quản lý Vị trí (Locations Administration) trên bảng điều khiển của bạn. Trong bảng tất cả các vị trí, xác định vị trí mong muốn, và ID vị trí sẽ được hiển thị ở cột đầu tiên.
   

   

4. Thêm mã Token API và ID Vị trí của bạn: Khi thực hiện một yêu cầu, hãy thêm cả mã token API và ID vị trí (nếu có) mà bạn đã lấy từ bảng điều khiển của mình vào các trường liên quan.

   

5. Nhận và Sử dụng Dữ liệu: API sẽ trả về dữ liệu ở định dạng JSON. Sau khi nhận dữ liệu, bạn có thể tích hợp nó vào hệ thống của mình hoặc sử dụng để phân tích thêm.

4. Truy cập dữ liệu máy đo qua API cục bộ

Cùng với API công khai (có thể truy cập từ bất kỳ đâu), chúng tôi cũng cung cấp một API cục bộ chỉ có thể được truy cập bởi các thiết bị trong cùng một mạng WiFi với máy đo AirGradient đang được chọn. Điều này cho phép các tổ chức mà muốn vận hành một máy đo hoặc mạng lưới trong mạng cục bộ của họ có thể truy cập dữ liệu và cài đặt cấu hình từ các thiết bị cục bộ.

Để biết thêm thông tin về AirGradient local API, vui lòng truy cập tài liệu tại máy chủ cục bộ.

1. Chuẩn bị môi trường: Đảm bảo máy đo AirGradient được kết nối WiFi và nằm trong cùng một mạng với thiết bị muốn truy xuất dữ liệu.

2. Truy xuất dữ liệu đo lường: Để truy xuất các thông số mới nhất, hãy mở trình duyệt và truy cập URL bên dưới với định dạng:
   

     http://airgradient_**{{SERIAL_NUMBER}}**.local/measures/current
   

   Hãy chắc chắn đã đổi {{SERIAL_NUMBER}} thành số sê-ri (bạn có thể tìm thấy số này ở mặt sau của máy đo) của máy đo mục tiêu, ví dụ:
   

     http://airgradient_aaaaaaaaaaaa.local/measures/current
   

   

3. Truy xuất cấu hình cục bộ: Để truy xuất cấu hình cục bộ, tương tự như điểm 2 nhưng định dạng URL như sau:
   

     http://airgradient_**{{SERIAL_NUMBER}}**.local/config
   

   

4. Nhận và Sử dụng Dữ liệu: API sẽ trả về dữ liệu ở định dạng JSON. Sau khi nhận dữ liệu, bạn có thể tích hợp nó vào hệ thống của mình hoặc sử dụng để phân tích thêm.

5. Câu hỏi thường gặp (FAQs)

Nếu bạn gặp bất kỳ vấn đề nào hoặc đang tìm kiếm thêm câu trả lời, vui lòng đọc các câu hỏi thường gặp dưới đây.

API AirGradient là gì?

API AirGradient là một công cụ do AirGradient cung cấp cho phép người dùng và tổ chức tự động lấy dữ liệu chất lượng không khí từ các máy chủ của AirGradient. Nó cho phép bạn tích hợp dữ liệu từ các máy đo của mình (và các máy đo công khai khác) vào các ứng dụng hoặc trang web của riêng bạn.

Tôi có thể nhận được loại dữ liệu nào thông qua API?

Bạn có thể lấy thông tin cho mọi chỉ số mà máy đo AirGradient đo được, chẳng hạn như PM_2.5, nhiệt độ và carbon dioxide. Bạn cũng có thể truy cập dữ liệu lịch sử giới hạn cho các máy đo.

Làm cách nào để bắt đầu sử dụng API?

Trước tiên, bạn cần nhận Mã Token API bằng cách kích hoạt quyền truy cập API trong Cài đặt Chung (General Settings) của bảng điều khiển AirGradient (dưới thẻ Kết nối - Connectivity). Bạn cũng có thể cần ID Vị trí (Location ID) cụ thể cho ( các) máy đo của mình, được tìm thấy trên trang Quản lý Vị trí (Locations Administration). Sau đó, bạn sử dụng mã token này (và ID Vị trí nếu cần) khi thực hiện các yêu cầu dữ liệu, theo hướng dẫn trong Tài liệu Swagger.

Tôi có cần kiến thức kỹ thuật để sử dụng API không?

Tài liệu này trình bày những kiến thức cơ bản về cách truy cập API. Tuy nhiên, nếu triển khai dữ liệu bạn nhận được vào một ứng dụng hoặc trang web tùy chỉnh, bạn có thể sẽ cần đến một lập trình viên có kinh nghiệm. Tài liệu này không đề cập đến các khía cạnh triển khai nâng cao đó.

API cung cấp dữ liệu ở định dạng nào?

API trả về dữ liệu được yêu cầu ở định dạng JSON, đây là một định dạng chuẩn mà máy có thể đọc được, phù hợp để sử dụng trong các ứng dụng.

Developed by AirGradient in Collaboration with the UNDP Global Centre Singapore CC-BY-SA