주차정책

실시간 주차면수 정보 연계 API 상세

홈 › 주차정책 › 민간주차장 정보 › 실시간 면수 연계 API
PDF 다운로드
REALTIME PARKING API

실시간 주차면수 정보 연계 API
사업자용 호출 명세

민간주차장 사업자가 자체 시스템에서 주기적으로 실시간 주차 정보를 구미시 통합주차정보시스템에 전송하는 API 명세입니다. 인증키(X-API-KEY)는 민간주차장 정보 개방 신청 후 승인 시 자동 발급됩니다.

REST / JSON UPSERT 저장 X-API-KEY
1 API 기본정보
엔드포인트
/api/private-park/hours
HTTP 메서드
PATCH
요청 형식
application/json (UTF-8)
응답 형식
application/json (UTF-8)
인증 방식
HTTP 헤더 X-API-KEY (UUID)
호출 주기
최소 1분 이상 권장 (사업자 자체 정책에 따름)
2 인증

민간주차장 정보 개방 신청이 승인되면 시스템이 UUID 형식의 API_KEY를 자동 발급합니다. 발급된 키는 마이페이지 또는 관리자로부터 안내받을 수 있으며, 모든 요청 시 HTTP 헤더에 다음과 같이 포함해야 합니다.

PATCH /api/private-park/hours HTTP/1.1
Host: parking.gumi.go.kr
Content-Type: application/json; charset=UTF-8
X-API-KEY: 12ab34cd-56ef-7890-abcd-ef1234567890

※ X-API-KEY 누락 또는 잘못된 키 사용 시 401 Unauthorized 응답이 반환됩니다.

3 요청 본문 (Request Body)
항목명(국문) 항목명(영문) 형식 필수 설명
주차장 코드park_cdString필수승인 시 발급된 주차장 코드(예: GM_PRVT74ED0186E3984C12)
총 주차면수tot_park_cntInteger필수전체 주차면수
현재 주차 대수now_park_cntInteger필수현재 점유 중인 주차면수(잔여 면수가 아님)

※ now_park_cnt는 0 ≤ now_park_cnt ≤ tot_park_cnt 범위여야 하며, 초과·음수 시 오류로 처리됩니다.

※ 주차장 식별은 X-API-KEY로 이루어집니다. park_cd는 확인용 값이며 서버 처리에는 사용되지 않습니다.

4 응답 본문 (Response Body)
항목명(국문) 항목명(영문) 형식 설명
처리 결과successbooleantrue: 정상 / false: 오류
주차장 코드parkCdString통합주차정보시스템 내부 신청번호(=APLY_NUM). 요청의 park_cd와 달리 접두사가 붙지 않습니다.
처리 메시지messageString오류 시 사유, 정상 시 "OK"
5 호출 예제

요청 예시

PATCH /api/private-park/hours HTTP/1.1
Host: parking.gumi.go.kr
Content-Type: application/json
X-API-KEY: 12ab34cd-56ef-7890-abcd-ef1234567890

{
    "park_cd"     : "GM_PRVT74ED0186E3984C12",
    "tot_park_cnt": 120,
    "now_park_cnt": 85
}

응답 예시 (정상)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true,
    "parkCd" : "PRVT74ED0186E3984C12",
    "message": "OK"
}

응답 예시 (오류 — 현재 대수가 총 면수 초과)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": false,
    "message": "현재 주차 대수가 총 주차면수를 초과할 수 없습니다."
}
6 에러 응답

모든 응답은 HTTP/1.1 200 OK로 반환되며, 처리 결과는 success 필드로 구분합니다(true: 정상 / false: 오류). 오류 시 message에 사유가 포함됩니다.

구분 사유 주요 메시지
인증 오류API_KEY 누락 / 무효 / 사용 정지"API_KEY 헤더가 누락되었습니다."
"유효하지 않은 API_KEY 이거나 사용 정지 상태입니다."
검증 오류필수 필드 누락 또는 값 검증 실패"tot_park_cnt/now_park_cnt 는 필수입니다."
"현재 주차 대수가 총 주차면수를 초과할 수 없습니다."
"주차면수는 음수일 수 없습니다."
본문 오류JSON 파싱 실패 / 본문 누락"요청 본문이 누락되었습니다."
"요청 본문이 올바른 JSON 형식이 아닙니다."
서버 오류예외 발생"실시간 정보 저장 중 오류가 발생했습니다."
7 발급 및 운영 안내
키 발급민간주차장 정보 개방 신청 → 승인 시 시스템이 UUID API_KEY 자동 발급
키 재발급관리자 화면(/admin/private/info) 상세에서 재발급 가능 (유출·교체 시)
키 회수위반·탈퇴 시 USE_YN='N'으로 사용 정지
호출 제한현재 별도 한도 없음 (남용 적발 시 제한 부과 가능)
저장 정책주차장당 1행 UPSERT (TBL_PRVT_PARK_FULL) — 마지막 수신값으로 갱신
PDF 다운로드