더매리지 API 문서

20~30대 급만남 서비스 더매리지(TheMarriage) 의 공개 REST API 문서입니다. 모든 응답은 application/json; charset=utf-8 형식이며, 시각은 UTC ISO-8601 로 표기합니다.

Base URL

https://api.themarriage.co.kr

항목	값
버전	`1.0.0`
프로토콜	HTTPS 전용 (HTTP 요청은 301 리다이렉트)
인증	공개 엔드포인트는 인증 불필요
요청 제한	IP 당 60 requests / min
문자 인코딩	UTF-8

대화형 문서는 Swagger UI 와 ReDoc 에서도 확인할 수 있고, 이 문서의 마크다운 원문은 api.md 에서 내려받을 수 있습니다.

1. 시스템

GET /api/health

서버 상태를 확인합니다. 헬스체크 및 모니터링 용도입니다.

요청 예시

curl https://api.themarriage.co.kr/api/health

응답 200 OK

{
  "status": "ok",
  "service": "themarriage",
  "version": "1.0.0",
  "time": "2026-08-24T04:12:33.482910+00:00"
}

2. 공개 데이터

GET /api/stats

서비스 전체 지표를 조회합니다.

응답 200 OK

{
  "total_members": 128400,
  "verified_rate": 0.982,
  "avg_match_minutes": 12,
  "today_matches": 1734,
  "age_2030_ratio": 0.94
}

필드	타입	설명
`total_members`	integer	누적 가입 회원 수
`verified_rate`	float	본인인증 완료 비율 (0~1)
`avg_match_minutes`	integer	평균 매칭 소요 시간(분)
`today_matches`	integer	오늘 성사된 매칭 수
`age_2030_ratio`	float	20~30대 회원 비중 (0~1)

GET /api/profiles

추천 프로필 목록을 조회합니다.

쿼리 파라미터

이름	타입	필수	기본값	설명
`region`	string	N	-	지역 필터 (예: `강남`, `판교`)
`min_age`	integer	N	`19`	최소 나이
`max_age`	integer	N	`39`	최대 나이
`limit`	integer	N	`20`	최대 반환 개수

요청 예시

curl "https://api.themarriage.co.kr/api/profiles?region=강남&min_age=25&max_age=32&limit=5"

응답 200 OK

{
  "count": 1,
  "items": [
    {
      "id": "p_1024",
      "nickname": "지우",
      "age": 27,
      "region": "강남",
      "job": "마케터",
      "tags": ["와인", "전시회", "주말여행"],
      "verified": true
    }
  ]
}

오류 400 Bad Request — min_age 가 max_age 보다 큰 경우

{ "detail": "min_age는 max_age보다 클 수 없습니다." }

GET /api/profiles/{profile_id}

프로필 한 건을 조회합니다.

요청 예시

curl https://api.themarriage.co.kr/api/profiles/p_1024

응답 200 OK

{
  "id": "p_1024",
  "nickname": "지우",
  "age": 27,
  "region": "강남",
  "job": "마케터",
  "tags": ["와인", "전시회", "주말여행"],
  "verified": true
}

오류 404 Not Found

{ "detail": "프로필을 찾을 수 없습니다: p_9999" }

3. 매칭

POST /api/signup

급만남 매칭을 신청합니다.

요청 본문

필드	타입	필수	제약	설명
`nickname`	string	Y	1~20자	닉네임
`age`	integer	Y	19~39	나이. 19세 미만은 가입할 수 없습니다.
`gender`	string	Y	`male` \| `female` \| `other`	성별
`region`	string	Y	1~30자	활동 지역
`phone`	string	Y	9~20자	연락처 (본인인증용)
`interests`	string[]	N	-	관심사 태그

요청 예시

curl -X POST https://api.themarriage.co.kr/api/signup \
  -H "Content-Type: application/json" \
  -d '{
        "nickname": "지우",
        "age": 27,
        "gender": "female",
        "region": "강남",
        "phone": "010-1234-5678",
        "interests": ["와인", "전시회"]
      }'

응답 201 Created

{
  "signup_id": "sg_9f2c41ab77de",
  "status": "pending",
  "message": "지우님, 매칭 신청이 접수되었습니다. 평균 12분 내 연결됩니다.",
  "created_at": "2026-08-24T04:12:33.482910+00:00"
}

오류 422 Unprocessable Entity — 나이 제한 위반 등 검증 실패

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["body", "age"],
      "msg": "Input should be greater than or equal to 19"
    }
  ]
}

GET /api/signup/{signup_id}

매칭 신청 내역을 조회합니다.

요청 예시

curl https://api.themarriage.co.kr/api/signup/sg_9f2c41ab77de

응답 200 OK

{
  "signup_id": "sg_9f2c41ab77de",
  "status": "pending",
  "created_at": "2026-08-24T04:12:33.482910+00:00",
  "nickname": "지우",
  "age": 27,
  "gender": "female",
  "region": "강남",
  "phone": "010-1234-5678",
  "interests": ["와인", "전시회"]
}

상태값(status)

값	설명
`pending`	접수 완료, 매칭 대기 중
`matched`	매칭 성사
`expired`	24시간 내 미성사로 만료
`cancelled`	사용자 취소

GET /api/matches

실시간 매칭 현황과 추천 프로필을 함께 반환합니다.

쿼리 파라미터

이름	타입	필수	기본값	설명
`limit`	integer	N	`5`	추천 프로필 개수

응답 200 OK

{
  "today_matches": 1734,
  "avg_match_minutes": 12,
  "recommended": [
    { "id": "p_1024", "nickname": "지우", "age": 27, "region": "강남", "job": "마케터", "tags": ["와인", "전시회", "주말여행"], "verified": true }
  ]
}

4. 오류 형식

모든 오류는 아래 형태의 JSON 으로 반환됩니다.

{ "detail": "오류 메시지" }

상태 코드	의미
`400`	잘못된 요청 파라미터
`404`	리소스를 찾을 수 없음
`422`	요청 본문 검증 실패
`429`	요청 제한 초과
`500`	서버 내부 오류

5. 이용 정책

본 서비스는 만 19세 이상 성인만 이용할 수 있으며, 가입 시 본인인증을 거칩니다.
수집한 연락처는 본인인증과 매칭 안내 목적 외에는 사용하지 않습니다.
API 응답의 프로필 데이터는 데모용 예시 데이터이며 실제 회원 정보가 아닙니다.
자동화된 대량 수집(스크래핑)은 금지되며, 위반 시 IP 차단될 수 있습니다.