에어코리아 측정소 실시간 대기질 응답을 오염물질별 구조화된 객체로 정규화합니다.

에어코리아 실시간 대기오염

대기질 등급 코드와 문자열 수치를 정리해 측정소 단위의 일관된 대기질 객체를 제공합니다.

엔드포인트

GET /v1/airkorea-realtime

Upstream

Base URL: https://apis.data.go.kr/B552584/ArpltnInforInqireSvc
Path: /getMsrstnAcctoRltmMesureDnsty

요청 파라미터

파라미터	타입	필수	기본값	설명
`stationName`	string	❌	`동작구`	측정소명 — 서울 구 이름 (예: 강남구, 종로구, 서초구)
`dataTerm`	string	❌	`DAILY`	데이터 기간 (DAILY/MONTH/3MONTH)

요청 예시

{
  "stationName": "동작구",
  "dataTerm": "DAILY"
}

응답 스키마

아래 스키마는 adapter의 Zod output schema에서 직접 생성됩니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "station": {
      "type": "string",
      "description": "측정소명"
    },
    "measuredAt": {
      "type": "string",
      "description": "측정 시각 (ISO 8601 KST)"
    },
    "pm10": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "미세먼지 (PM10)"
    },
    "pm25": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "초미세먼지 (PM2.5)"
    },
    "no2": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "이산화질소 (NO2)"
    },
    "o3": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "오존 (O3)"
    },
    "so2": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "아황산가스 (SO2)"
    },
    "co": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "일산화탄소 (CO)"
    },
    "khai": {
      "type": "object",
      "properties": {
        "value": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "grade": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "good",
                "moderate",
                "bad",
                "very_bad"
              ]
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "value",
        "grade"
      ],
      "additionalProperties": false,
      "description": "통합대기환경지수 (KHAI)"
    }
  },
  "required": [
    "station",
    "measuredAt",
    "pm10",
    "pm25",
    "no2",
    "o3",
    "so2",
    "co",
    "khai"
  ],
  "additionalProperties": false
}

응답 예시

{
  "data": {
    "station": "동작구",
    "measuredAt": "2025-03-22T14:00:00+09:00",
    "pm10": {
      "value": 45,
      "grade": "moderate"
    },
    "pm25": {
      "value": 18,
      "grade": "good"
    },
    "no2": {
      "value": 0.027,
      "grade": "good"
    },
    "o3": {
      "value": 0.025,
      "grade": "good"
    },
    "so2": {
      "value": 0.003,
      "grade": "good"
    },
    "co": {
      "value": 0.4,
      "grade": "good"
    },
    "khai": {
      "value": 54,
      "grade": "moderate"
    }
  },
  "pagination": null,
  "meta": {
    "source": "airkorea-realtime",
    "fetchedAt": "2026-03-24T00:00:00.000Z"
  }
}

정규화 사항

items 배열의 첫 측정값을 station/measuredAt 기준 단일 객체로 정규화합니다.
pm10/pm25/no2/o3/so2/co/khai 값을 { value, grade } 구조로 통일합니다.
'-'·빈 값은 null로 변환하고 등급 숫자는 good/moderate/bad/very_bad enum으로 매핑합니다.
dataTime 문자열을 ISO 8601 KST measuredAt 값으로 변환합니다.

에어코리아 실시간 대기오염

On this page