Hotzone Backend API

아동 실종 시 핫존(가능성이 높은 지역)을 분석하는 FastAPI 기반 백엔드 서비스입니다.

🚀 주요 기능

• 나이대별 핫존 분석: 아동의 나이에 따라 다른 검색 반경과 장소 가중치 적용
• 지리적 위치 분석: OpenStreetMap 데이터를 활용한 주변 장소 검색
• 핫존 점수 계산: 사용 빈도와 위험도를 고려한 종합 점수 산출
• 인터랙티브 지도: Folium을 활용한 시각적 핫존 표시
• RESTful API: JSON 기반 API 및 HTML 지도 뷰 제공

📋 나이대별 설정

나이대	검색 반경	주요 관심 장소
1-4세	1km	놀이터, 공원, 유치원, 학교, 키즈카페
5-8세	1.3km	놀이터, 공원, 유치원, 학교, 주거지역
9-11세	3.2km	놀이터, 공원, 학교, 주거지역
12-14세	8km	공원, 학교, 대학, 상점
15-16세	23km	학교, 대학, 버스정류장, 지하철역, 상점

🛠️ 설치 및 실행

1. 의존성 설치

pip install -r requirements.txt

2. 서버 실행

uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. API 문서 확인

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📡 API 엔드포인트

1. 헬스 체크

GET /health

2. 핫존 분석 (JSON)

POST /api/hotzone
Content-Type: application/json

{
  "location_name": "서울시 강남구",
  "child_age": 8
}

3. 핫존 지도 (HTML)

GET /map/{location_name}/{child_age}

📊 응답 형식

핫존 분석 응답

{
  "scored_places": [
    {
      "name": "장소명",
      "place_type": "장소유형",
      "distance_km": 0.5,
      "hotzone_score": 2.34,
      "lat": 37.5665,
      "lon": 126.9780
    }
  ],
  "map_html": "<iframe>...</iframe>",
  "center_coords": [37.5665, 126.9780],
  "search_radius_km": 1.3
}

🔧 핵심 알고리즘

핫존 점수 계산

핫존 점수 = (사용 빈도 가중치 / 거리) - (위험도 가중치 × 거리)

• 사용 빈도: 해당 장소 유형이 아동에게 얼마나 매력적인지
• 위험도: 해당 장소 유형의 잠재적 위험성
• 거리: 실종 위치로부터의 거리

🗺️ 지도 시각화

• 빨간 마커: 실종 추정 위치
• 파란 원: 검색 반경
• 색상 마커: 핫존 점수에 따른 색상 구분
  • 🔴 높은 점수 (빨간색)
  • 🟡 중간 점수 (노란색)
  • 🟢 낮은 점수 (초록색)

🚨 주의사항

1. API 호출 제한: OpenStreetMap API 사용 시 과도한 요청을 피해주세요
2. 정확성: 지오코딩 결과는 100% 정확하지 않을 수 있습니다
3. 데이터 소스: OpenStreetMap 데이터의 완성도에 따라 결과가 달라질 수 있습니다

🤝 기여하기

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다.

📞 문의

프로젝트에 대한 문의사항이 있으시면 이슈를 생성해주세요.