airkorea-statistics-repository

Die 대기오염통계 서비스 (ArplTStatsSvc)-OpenAPI von 한국환경공단 에어코리아 wird als MCP (Model Context Protocol)-Server for Claude bereitgestellt. Damit können Echtzeit-Durchschnittswerte je 시도/시군 sowie Tages- und Monatsdurchschnittswerte je Messstation (측정소) abgerufen werden.

Es ist die letzte Stufe der dreistufig aufgeteilten Entwicklung von 에어코리아; vorausgesetzt wird die Verwendung zusammen mit Stufe 1 (airkorea-realtime-mcp) und Stufe 2 (airkorea-forecast-alert-mcp).

Verfügbare Funktionen

Maßeinheiten: SO2/CO/O3/NO2 = ppm, PM10/PM2.5 = ㎍/㎥

Zum Umfang dieser MCP (Wichtig)

Enthalten sind nur die 4 Operationen, die zur 서비스 (ArpltnStats 대기오염대기오염통계) gehören. Die folgenden zwei Operationen waren ursprünglich Kandidaten für Stufe 3, gehören aber tatsächlich zu anderen Servicedienstleistungsgruppen und wurden aus diesem Umfang ausgenommen (Begründung siehe Abschnitt 0-1 der Datei DEVPLAN.md; Entscheidungsweg siehe DEVLOG.md):

• getTMstandStationsCrdnt (TM-Standardkoordinaten abrufen) — gehört zur Messstation-Abfragedienst (MsrstnInfoInqireSvc), also dieselben Serviced-group wie Stufe 1 (airkorea-realtime-mcp)

• getUnityAirEnvrnIdexSnstiveAboveMsrstnList (Liste der Messstationen mit integriertem Luftqualitätsindex „schlecht“ oder höher abrufen) — gehört zur Air-Quality-Information-Abfragedienst (ArpltnInforInqireSvc), dieselbe Serviced-group wie Stufen 1 und 2

Ob beide Operationen in den Repositories der Stufen 1 und 2 ergänzt werden, wird separat besprochen (zurückgestellt).

Installation und Ausführung

pip install -r requirements.txt
cp .env.example .env  # AIRKOREA_SERVICE_KEY 입력
python server.py

Umgebungsvariablen

Hinweis: Zur Nutzung dieses MCP muss der 대기오염통계 서비스 (ArpltnStatsSvc) bei der öffentlichen Datenportal (공공데이터포털) ومیPhone summen separate Nutzungsantrag (pro Service-ID einzeln Antrag) gestellt worden sein. The Wirkunste is actually with 1~2 Hours.

Bereitstellung (fly.io)

fly launch --no-deploy
fly secrets set AIRKOREA_SERVICE_KEY=발급받은키
flyctl deploy

Verbindungsadresse nach dem Deployment:

https://airkorea-statistics-mcp.fly.dev/mcp

Rate Limit

Da es sich um einen ohne Authentifizierung zugänglichen öffentlichen Server handelt, gilt ein 3-stufiges Rate Limit-Basis auf IP:

• Mehr als 3 Aufrufe pro Minute: 429

• 5 Verstöße innerhalb einer Stunde: Sperre für 24 Stunden

• Mehr als 30 Aufrufe pro Tag (rolling 24h): 429

Bei Bereitstellung auf mehreren Maschinen sind die In-Memory-Zähler je Maschine getrennt, wodurch das tatsächliche Grenze proportional zur Maschinenzahl gelockert werden kann.

Bekannte Limitationen (praktisch bestätigt, 2026-08-23)

• Numbers fields kommen als JSON-String und werden im Code sicher nach float konvertiert. Fehlender-Repräsentation ist nicht "-", sondern ein Leertype ("") (getestet bei khaiValue, pm10Value usw.).

• Es wurde bestätigt, dass die Antwort von getCtPrvnMesureSidoLIst tatsächlich das Feld khaiValue enthält.

• Wird sidoName=광주 oder 전남 übergeben, totalCount=0 (no data) zurückgegeben — für beide Regionen muss der kombinierte Wert 전남광주 verwendet werden, um normale Daten zu erhalten (Abweichendes reales Verhalten gegenüber dem Spezifikationen).

• Fehlerantworten werden innerhalb des real gemessenen Bereichs (Codes 30, 10) normal von JSON zurückgegeben. Ein XML-Fallback-Parser ist implementiert, aber die realen XML-Fehler-Beschreibungen ließen sich nicht reproduzieren — falls zukünftig XML-Fälle auftreten, werden diese in DEVLOG.md zusätzlich dokumentiert.

• SERVICETIMEOUT (504) konnte im lokalen Test nichts reproduziert werden — catches-Logik (max. 3 Versuche) ist implementiert, aber das Verhalten bei echten Timeouts nicht bestätigt.

Daten Quellen

• Anbietende Institution: 한국환경공단 (Im Auftrag des 환경부)

• Plattform: Daten öffentliche Portal (public (data.go.kr))

• API-Name: 한국환경공단_에어코리아_대기오염통계 현황 (Arpltn환 공예구)

• Lizenz: öffentliche "만" ko-org Tel, (Quellennameangabe - Keine Bearbeitung)

Lizenz

MIT License (für den Code selbst). Die Originaldaten бази "공 van" folgen der oben를 genannten Lizenrechte.