{"id":47737968,"url":"https://github.com/baeksj/ha-kma-weather","last_synced_at":"2026-04-02T23:03:33.906Z","repository":{"id":348655843,"uuid":"1199190526","full_name":"baeksj/ha-kma-weather","owner":"baeksj","description":"Korea Meteorological Administration weather integration for Home Assistant","archived":false,"fork":false,"pushed_at":"2026-04-02T15:46:54.000Z","size":354,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T19:55:38.009Z","etag":null,"topics":["custom-integration","hacs","home-assistant","kma","weather"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/baeksj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T05:56:19.000Z","updated_at":"2026-04-02T15:46:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/baeksj/ha-kma-weather","commit_stats":null,"previous_names":["baeksj/ha-kma-weather"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/baeksj/ha-kma-weather","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baeksj%2Fha-kma-weather","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baeksj%2Fha-kma-weather/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baeksj%2Fha-kma-weather/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baeksj%2Fha-kma-weather/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/baeksj","download_url":"https://codeload.github.com/baeksj/ha-kma-weather/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/baeksj%2Fha-kma-weather/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31318151,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T21:35:00.834Z","status":"ssl_error","status_checked_at":"2026-04-02T21:34:59.806Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-integration","hacs","home-assistant","kma","weather"],"created_at":"2026-04-02T23:03:33.204Z","updated_at":"2026-04-02T23:03:33.885Z","avatar_url":"https://github.com/baeksj.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KMA Weather for Home Assistant\n\n`KMA Weather`는 대한민국 기상청(KMA) 단기예보 OpenAPI를 이용해 Home Assistant에 현재 날씨, 시간별 예보, 일별 예보를 제공하는 custom integration입니다.  \nHACS Custom Repository로 설치할 수 있도록 구성되어 있습니다.\n\n## 주요 기능\n\n- 기상청 초단기실황 `getUltraSrtNcst` 조회\n- 기상청 초단기예보 `getUltraSrtFcst` 조회\n- 기상청 단기예보 `getVilageFcst` 조회\n- 위도/경도를 기상청 DFS 격자(`nx`, `ny`)로 자동 변환\n- Home Assistant `zone` 엔티티를 이용한 설정\n- 시간별 예보 / 일별 예보 제공\n- 일시적 API 장애 시 마지막 정상 데이터를 유지하는 실패 허용 로직\n- HACS 설치를 위한 `brand/` 자산 포함\n\n## 설치 전 준비\n\n이 integration을 사용하려면 먼저 `data.go.kr`에서 기상청 OpenAPI 활용 신청을 하고 서비스 키를 발급받아야 합니다.\n\n준비물:\n\n- `data.go.kr` 계정\n- Home Assistant 설정에서 생성한 지역(`zone`)\n- 발급받은 기상청 API 서비스 키\n\n기본으로 필요한 API:\n\n- `기상청_단기예보 조회서비스`\n\n환경 구성에서 선택적으로 확장할 수 있는 추가 API:\n\n- `기상청_생활기상지수 조회서비스(3.0)`\n- `한국환경공단_에어코리아_대기오염정보`\n- `기상청_꽃가루농도위험지수 조회서비스(3.0)`\n- `기상청_중기예보 조회서비스`\n\n## data.go.kr API 신청 및 발급 절차\n\n아래 절차는 `공공데이터포털(data.go.kr)`에서 기본 API인 `기상청_단기예보 조회서비스`를 처음 신청하는 기준으로 정리했습니다.\n\n1. `https://www.data.go.kr`에 로그인합니다.\n2. 검색창에서 `기상청 단기예보 조회서비스` 또는 `VilageFcstInfoService_2.0` 관련 API를 찾습니다.\n3. 상세 페이지에서 제공 형식이 `OpenAPI`인지 확인합니다.\n4. 활용 목적과 애플리케이션 정보를 입력해 `활용신청`을 진행합니다.\n5. 신청이 승인되면 마이페이지 또는 해당 API 상세 화면에서 `일반 인증키(Encoding)` / `일반 인증키(Decoding)`를 확인할 수 있습니다.\n6. Home Assistant 설정 화면에는 보통 `Decoding` 키를 넣는 것이 가장 덜 헷갈립니다.\n\n실제로 많이 막히는 지점:\n\n- 신청 직후 바로 호출되지 않을 수 있습니다.\n승인까지 약간의 시간이 걸릴 수 있으니, 호출이 실패하면 잠시 후 다시 확인하는 편이 좋습니다.\n\n- 같은 API 이름처럼 보여도 세부 서비스가 다를 수 있습니다.\n이 integration은 기상청 단기예보 계열 API를 전제로 작성되어 있으므로, 초단기실황/초단기예보/단기예보를 포함하는 서비스인지 확인해야 합니다.\n\n- `Encoding` 키를 그대로 붙여 넣으면 호출 URL에서 다시 인코딩되며 실패하는 경우가 있습니다.\n설정값으로는 `Decoding` 키를 사용하는 편이 안전합니다.\n\n권장 확인 순서:\n\n1. API 상세 페이지에서 `활용신청` 완료 여부를 확인합니다.\n2. `일반 인증키(Decoding)`를 복사합니다.\n3. data.go.kr 제공 테스트 화면이나 샘플 호출에서 응답이 정상인지 확인합니다.\n4. 그다음 Home Assistant integration 설정에 같은 키를 입력합니다.\n\n추가 API를 쓰고 싶다면:\n\n- 같은 `data.go.kr` 서비스 키를 재사용합니다.\n- 대신 사용하려는 각 OpenAPI 서비스는 별도로 `활용신청`해야 할 수 있습니다.\n- 즉, 키를 새로 발급받는 개념보다 `원하는 API 서비스에 대한 사용 승인`이 되었는지가 중요합니다.\n\n## Home Assistant 사전 준비\n\n이 integration은 Home Assistant에 등록된 지역(`zone`) 정보를 사용합니다.\n\n권장 방식은 Home Assistant 설정 화면에서 지역을 생성하고, 해당 지역에 정확한 위도/경도를 입력하는 것입니다.\n\n일반적인 흐름:\n\n1. Home Assistant `설정`에서 지역(`zone`)을 생성합니다.\n2. 지역 이름을 정하고, 사용할 위치의 정확한 위도/경도를 입력합니다.\n3. 이 integration 설정 시 해당 지역을 선택합니다.\n4. 선택한 좌표를 기준으로 기상청 DFS 격자(`nx`, `ny`)를 계산합니다.\n5. 같은 좌표를 기준으로 공공데이터에서 제공하는 위치/행정구역 후보를 매핑합니다.\n6. 매핑된 후보 중 가장 적절한 지역을 선택해 생활기상지수 등 부가 데이터를 연결합니다.\n\n즉, 사용자는 Home Assistant 안에서 위치를 관리하고, integration은 그 위치 좌표를 기준으로 기상청 예보 격자와 공공데이터 행정구역을 연결하는 방식입니다.\n\n## HACS 설치 방법\n\n1. HACS에서 `Integrations`로 이동합니다.\n2. 우측 상단 메뉴에서 `Custom repositories`를 엽니다.\n3. 저장소 URL에 `https://github.com/baeksj/ha-kma-weather`를 입력합니다.\n4. Category는 `Integration`으로 선택합니다.\n5. `KMA Weather`를 검색해 설치합니다.\n6. Home Assistant를 재시작합니다.\n7. `설정 → 기기 및 서비스 → 통합 추가`에서 `KMA Weather`를 추가합니다.\n\n설정 시 입력값:\n\n- API key: `data.go.kr`에서 발급받은 서비스 키\n- Location name: Home Assistant에 표시할 이름, 비워두면 기본 이름 사용\n- Zone: 설정에서 생성한 Home Assistant 지역(`zone`)\n\n## 환경 구성으로 추가 API 확장\n\n기본 설치가 끝나면 `설정 \u003e 기기 및 서비스 \u003e KMA Weather \u003e 구성`에서 추가 API를 선택적으로 연결할 수 있습니다.\n\n환경 구성 화면의 `select` 항목은 다음 용도로 사용됩니다.\n\n- 어떤 공공데이터 API를 추가로 사용할지 선택\n- 해당 API를 사용하려면 `data.go.kr`에서 어떤 서비스를 활용신청해야 하는지 안내\n- 적용 후 어떤 센서가 새로 생성되는지 안내\n\n즉, 최초 설치는 기본 날씨 기능 중심으로 끝내고, 이후 환경 구성에서 필요한 기능만 켜는 구조입니다.\n\n추가 API 목록:\n\n- `기상청_생활기상지수 조회서비스(3.0)`\n  - 안내 내용: 자외선지수, 대기확산지수용 API라는 점을 표시\n  - 추가 센서 예시: `KMA UV Index`, `KMA Air Diffusion Index`\n- `한국환경공단_에어코리아_대기오염정보`\n  - 안내 내용: 대기질 관련 API라는 점을 표시\n  - 추가 센서 예시: 미세먼지, 초미세먼지, 통합대기환경지수 계열\n- `기상청_꽃가루농도위험지수 조회서비스(3.0)`\n  - 안내 내용: 꽃가루 위험도 관련 API라는 점을 표시\n  - 추가 센서 예시: `KMA Pine Pollen Risk`, `KMA Oak Pollen Risk`, `KMA Weed Pollen Risk`\n- `기상청_중기예보 조회서비스`\n  - 안내 내용: 중기예보 확장용 API라는 점을 표시\n  - 추가 센서 예시: `KMA Mid-term Forecast Summary`, `KMA Mid-term Min Temperature`, `KMA Mid-term Max Temperature`\n\n현재 구현 기준:\n\n- 기본 API `기상청_단기예보 조회서비스`는 설치 시 사용됩니다.\n- 추가 API 중 현재 환경 구성에 실제 연결된 항목은 아래 4개입니다.\n- `기상청_생활기상지수 조회서비스(3.0)` → `KMA UV Index`, `KMA Air Diffusion Index`\n- `한국환경공단_에어코리아_대기오염정보` → `AirKorea Station`, `AirKorea PM10`, `AirKorea PM2.5`, `AirKorea O3`, `AirKorea NO2`, `AirKorea CO`, `AirKorea SO2`, `AirKorea Integrated Air Quality Index`\n- `기상청_꽃가루농도위험지수 조회서비스(3.0)` → `KMA Pine Pollen Risk`, `KMA Oak Pollen Risk`, `KMA Weed Pollen Risk`\n- `기상청_중기예보 조회서비스` → `KMA Mid-term Forecast Summary`, `KMA Mid-term Min Temperature`, `KMA Mid-term Max Temperature`\n\n## 수동 설치 방법\n\n1. 이 저장소의 `custom_components/kma_weather` 디렉터리를 Home Assistant 설정 디렉터리의 `custom_components` 아래로 복사합니다.\n2. Home Assistant를 재시작합니다.\n3. `설정 → 기기 및 서비스 → 통합 추가`에서 `KMA Weather`를 추가합니다.\n\n## 동작 방식\n\n- 설정에서 선택한 지역(`zone`)의 위도/경도를 읽습니다.\n- 해당 좌표를 기상청 DFS 격자로 변환합니다.\n- 같은 좌표를 기반으로 공공데이터 위치/행정구역 코드를 가장 가깝게 매핑합니다.\n- 초단기실황, 초단기예보, 단기예보 API를 순차 호출합니다.\n- 현재 날씨와 시간별/일별 예보를 weather 엔티티로 노출합니다.\n\n## 장애 처리\n\nAPI가 일시적으로 실패해도 바로 엔티티를 unavailable로 바꾸지 않고, 마지막 정상 데이터를 일정 횟수까지 유지합니다.\n\n- 기본 연속 실패 허용 횟수: `3`\n- 옵션에서 변경 가능\n- 허용 횟수 미만이면 마지막 정상 데이터 유지\n- 허용 횟수 이상이면 coordinator 갱신 실패로 처리\n\n관련 속성:\n\n- `consecutive_failures`\n- `failure_tolerance`\n- `data_stale`\n\n## 현재 제약 사항\n\n- 설정 시 Home Assistant 지역(`zone`)이 반드시 필요합니다.\n- 선택한 지역의 좌표를 나중에 변경해도 기존 config entry에 즉시 자동 반영되지는 않을 수 있습니다.\n- 주소 검색 기반 설정 UX는 아직 포함되어 있지 않습니다.\n- 기상청 응답값의 일부 세부 카테고리 매핑은 계속 보강할 수 있습니다.\n\n## 개발 확인\n\n저장소 루트에서 아래 명령으로 간단한 문법 확인을 할 수 있습니다.\n\n```bash\npython3 -m compileall custom_components/kma_weather\n```\n\n## 배포 체크리스트\n\n- `custom_components/kma_weather/manifest.json`의 `version`을 새 태그와 맞춥니다.\n- Git 태그와 GitHub Release 버전을 동일하게 맞춥니다.\n- GitHub 저장소 description과 topics를 설정합니다.\n- HACS에서 읽는 `hacs.json`의 Home Assistant 최소 버전을 실제 지원 범위와 맞춥니다.\n\n권장 GitHub topics:\n\n- `home-assistant`\n- `hacs`\n- `custom-integration`\n- `weather`\n- `kma`\n- `korea`\n\n## 참고\n\n- 공공데이터포털: `https://www.data.go.kr`\n- 기상청 단기예보 계열 API는 발표 시각과 실제 조회 가능 시각 사이에 지연이 있을 수 있습니다.\n- 실제 운영 시에는 테스트 키보다 운영에 사용할 키를 별도로 관리하는 편이 안전합니다.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaeksj%2Fha-kma-weather","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaeksj%2Fha-kma-weather","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaeksj%2Fha-kma-weather/lists"}