MASHONG · DEVELOPER API · v1.1

날씨를 앱과 웹에 연결하세요.

현재 날씨, 시간별·일별 예보, 제공 지역의 기상 경보를 하나의 API로 조회합니다.

빠른 시작

서비스 인증키는 서버 환경변수에 보관합니다. 앱·웹은 여러분의 인증된 백엔드에서 발급받은 5분 임시 토큰을 사용합니다.

GET /v1/weather?latitude=36.81&longitude=127.11&hours=24&days=7
Authorization: Bearer <service-key-or-session-token>

경로	응답
GET /v1/weather	현재 + 시간별 + 일별
GET /v1/weather/current	현재 기온·체감·습도·바람
GET /v1/weather/hourly	최대 48시간
GET /v1/weather/daily	최대 10일
GET /v1/weather/alerts	지원 여부 + 경보 원문 · countryCode 필수
POST /v1/tokens	서버에서만 임시 토큰 발급
GET /ready	서버용 인증·서명 설정 점검

앱·웹 인증

기존 로그인 세션으로 사용자를 검증합니다.
백엔드가 서비스키로 POST /v1/tokens를 호출합니다.
앱·웹에는 반환된 accessToken만 전달하고 메모리에 보관합니다.
토큰이 만료되면 백엔드에서 새로 발급받습니다.

POST /v1/tokens
Content-Type: application/json
Authorization: Bearer <server-only-service-key>

{"subject":"opaque-user-uuid","origin":"https://your-app.example"}

웹은 정확한 HTTPS origin을 운영자에게 등록해야 합니다. 현재 등록되지 않은 출처는 차단됩니다. 네이티브 앱은 origin을 생략합니다. 익명 사용자는 백엔드에서 challenge 검증·호출 제한을 적용한 뒤 토큰을 발급하세요.

화면에 표시하기

summary.current · summary.hourly · summary.daily에 섭씨·mm·km/h·퍼센트가 정리되어 있습니다. 값이 없으면 null이며, 0과 구분하세요. 한국어 상태 문구와 범용 아이콘 이름도 포함됩니다.

data는 Apple 데이터셋과 metadata를 유지합니다. 원본의 습도·강수확률은 0~1 비율입니다. fetchedAt과 retrievedAt은 조회 시각이고, 실제 자료 기준은 asOf와 forecastStart입니다.

날씨를 표시할 때 응답의 attribution에 있는 Apple Weather 공식 로고와 모든 출처 링크를 함께 표시하세요. 경보는 원문과 이벤트 링크를 유지하세요.

위치와 오류 처리

사용자가 위치 사용을 선택했을 때만 위치 권한을 요청하고, 거절하면 지역 선택을 제공하세요. 좌표는 소수 둘째 자리로 줄여 전송됩니다. 지역명 검색은 앱의 신뢰할 수 있는 지오코더에서 처리합니다.

401은 토큰 갱신, 429는 Retry-After 이후 재시도, 502·503·504는 조회 불가 상태로 처리하세요. 실패한 날씨를 추측하거나 오래된 값을 현재 날씨로 표시하지 마세요.