IonoFlux Python SDK

Python 3.11+동기 클라이언트PolyForm-Noncommercial-1.0.0

IonoFlux API의 공식 Python 클라이언트입니다. 우주기상·태양·지자기 데이터, 경보, 공개 데이터 메타데이터를 지원하며 API의 원본 JSON을 그대로 돌려줍니다.

pip install ionoflux

PyPI GitHub 릴리스 노트

1. Server 키 만들기

계정 페이지에서 로그인한 뒤 Server API 키를 만드세요. Python은 브라우저 밖에서 실행되므로 Web 키는 403을 반환할 수 있습니다. 키는 소스 저장소, 브라우저, 공유 노트북 출력에 남기지 마세요.

현재 키 발급 화면은 Server 키에도 서비스 URL을 요구합니다. 웹사이트가 없는 노트북·배치 작업이라면 기존 정책에 맞는 서비스 URL을 입력하세요. SDK는 키를 발급하거나 이 요구를 우회하지 않습니다.

export IONOFLUX_API_KEY='your-server-key'

2. 빠른 시작

from ionoflux import Client

with Client() as client:
    current = client.space_weather.current()
    print(current.data)  # Original JSON fields, including nulls and timestamp strings
    print(current.rate_limit.remaining)

Client()는 IONOFLUX_API_KEY에서 키를 읽고, Client(api_key="...")가 이를 우선합니다. sources()와 data.status()는 키 없이 호출됩니다. 요청 시각은 시간대가 있는 datetime이어야 하며 UTC로 전송됩니다.

from datetime import UTC, datetime
from ionoflux import Client, RateLimitError

with Client(timeout=10.0, max_retries=1) as client:
    try:
        series = client.solar.flux(
            start=datetime(2026, 10, 1, tzinfo=UTC),
            end=datetime(2026, 10, 2, tzinfo=UTC),
            interval="1h",
            limit=100,
        )
        print(series.data["unit"], series.data["attribution"])
    except RateLimitError as error:
        print(error.retry_after, error.rate_limit.reset_seconds)

지원 호출

모든 호출은 .data(JSON), .raw_body, .status_code, .headers, .rate_limit을 가진 APIResponse를 반환합니다. 시계열 호출은 start, end, interval, limit 인자를 공통으로 씁니다.

`client.space_weather.current()`	현재 지표와 데이터 신선도
`client.solar.flux(...)`	태양 플럭스 지수(SFI)
`client.solar.sunspots(...)`	흑점 수(출처 swpc 또는 silso)
`client.solar.xray(...)`	태양 X선 플럭스(long 또는 short 대역)
`client.solar.wind(...)`	태양풍 속도·밀도·Bt·Bz
`client.geomagnetic.kp(...)`	Kp 지수(출처 swpc 또는 gfz, 예보 포함 선택)
`client.geomagnetic.ap(...)`	Ap 지수
`client.statistics(metric, ...)`	기간별 지표 요약 통계
`client.alerts.list(...)`	우주기상 경보(since, category, limit)
`client.alerts.scales()`	NOAA R/S/G 등급과 전망
`client.sources()`	공개 제공 기관 목록과 수집 신선도(키 불필요)
`client.data.status(dataset=None)`	데이터셋 공개 현황(키 불필요)

지원 범위와 제약

이번 버전은 비동기 클라이언트, pandas/DataFrame 변환, TEC/MUF 지도, 경로 예측, 관측소, WSPR/PSK 조회를 제공하지 않으며 향후 과제입니다. 경로 예측과 지도는 REST API를 직접 호출하세요.

GET만 구현되어 있습니다. 재시도는 최대 3회(기본 1회)이며 연결 오류·타임아웃·HTTP 502/503/504에만 적용되고, 재시도도 하루 1,000회 한도에 포함될 수 있습니다. 리다이렉트는 따르지 않습니다.

자세히: API 계약과 제약 · 변경 기록 · 한국어 README

라이선스와 약관

SDK 코드는 PolyForm Noncommercial License 1.0.0를 따릅니다. 개인·취미 사용과 라이선스가 명시한 교육·연구 등 기관 사용을 포함한 비상업적 사용을 허용합니다. 그 범위를 벗어난 상업적 사용에는 별도 서면 라이선스가 필요하며, OSI 오픈소스 라이선스가 아닙니다.

SDK를 재배포할 때는 라이선스 조항과 NOTICE의 Required Notice를 유지하세요:

Required Notice: IonoFlux (https://ionoflux.runvia.app)

SDK 라이선스는 코드에만 적용됩니다. API 이용, API 결과의 출처 표기, 원 제공 기관의 데이터 라이선스는 별개이므로 각 응답의 source와 attribution을 유지해 주세요.