앱에서 실시간 자전거 이용가능성을 표시하려면 반환된 수량과 최신성, 차량 이용 가능 조건을 함께 연결하세요. 관찰값은 데이터 출처가 특정 시점에 알고 있던 정보를 나타내며, 도착 시점까지 자전거가 남아있다는 보장은 아닙니다.
ROOTE 모빌리티 계약은 스테이션, 개별 차량과 그 상태를 구분합니다. 인터페이스는 미확인 값, 빈 스테이션, 일시적으로 이용 불가능한 출처 상태를 혼동하지 않고 표현해야 합니다.
스테이션과 개별 차량 구분
스테이션은 자전거 수와 반환 가능한 자리 수 집계를 제공할 수 있습니다. 개별 차량은 이용 가능 여부와 기타 관련 정보를 갖습니다. 스테이션을 자전거로 계산하거나 동일 재고를 나타내는 집계를 중복 합산하지 마세요.
ROOTE 모빌리티 DTO에서 availability.bikes와 availability.docks는 미확인일 수 있습니다. 추진 방식이나 배터리 관련 필드는 존재하고 계약상 해석 가능할 때만 표시해야 합니다.
최신성 및 타임스탬프 읽기
| 필드 | 해석 |
|---|---|
| freshness.state | 보고 상태: fresh(신선), stale(오래됨), unknown(알 수 없음), static(정적) |
| freshness.source_updated_at | 알려진 경우 출처의 갱신 시각 |
| freshness.received_at | 계약에 명시된 수신 시각 |
| freshness.expires_at | 알려진 경우 유효 만료 시각 |
| availability.bikes | 알려진 수량 또는 미확인 값 |
| pickup.enabled 및 pickup.state | 스테이션에서 자전거 대여 가능성 정보 |
호출 시각이 관찰 시각과 자동 일치하지 않습니다. 예를 들어 10시에 받은 결과에 9시 45분에 갱신된 출처 데이터가 포함될 수 있습니다. 단순히 인터페이스 수신 시각으로 "지금 갱신됨"을 표시하지 마세요.
별도의 표시 상태 예상하기
| 수신된 데이터 | 예상 표시 |
|---|---|
| 알려진 수량 및 신선한 데이터 | 관찰된 수량과 시간 표시 |
| 수량 0 | 관찰된 자전거 없음과 시간 맥락 |
| 수량 null | 이용 가능성 미확인 |
| stale 상태 또는 만료된 데이터 | 오래된 데이터; 새로 고침 필요 제안 |
| pickup.enabled=false | 집계가 긍정적이어도 대여 불가능 |
| 검색 오류 | 일시적으로 이용 불가, 0으로 변환하지 않음 |
unknown 또는 static 상태를 신선함으로 분류하지 마세요. 스테이션 데이터는 안정적일 수 있으나 집계는 빠르게 변할 수 있습니다. 또한 응답에서 요구하는 경고와 저작권 표시는 유지하세요.
렌더링 전 정규화 예시
다음 함수는 ROOTE 스키마에 검증된 스테이션으로부터 표시 상태를 생성합니다. 완전한 응답 검증기는 아니며, 인터페이스 번역키에서 라벨을 받아 표시해야 합니다.
function availabilityView(station, now = Date.now()) {
const freshness = station.freshness;
const expiresAt = freshness.expires_at
? Date.parse(freshness.expires_at) : null;
const expired = expiresAt !== null &&
Number.isFinite(expiresAt) && expiresAt <= now;
if (station.pickup.enabled === false ||
station.pickup.state === 'unavailable_now') {
return { state: 'pickup_unavailable', count: null };
}
if (expired || freshness.state === 'stale') {
return { state: 'stale', count: null };
}
const count = station.availability.bikes;
if (freshness.state !== 'fresh' || count === null ||
!Number.isFinite(count) || count < 0) {
return { state: 'unknown', count: null };
}
return {
state: count === 0 ? 'empty' : 'observed', count,
sourceUpdatedAt: freshness.source_updated_at,
receivedAt: freshness.received_at,
pickupState: station.pickup.state
};
}관찰 상태라도 pickupState=unknown을 대여 확정으로 바꾸지 마세요. 집계는 여전히 관찰값입니다. 제품에서 사용자에게 스테이션 선택 정보를 제공한다면 대여 가능 맥락을 표시하세요.
불필요한 호출 중복 없이 새로 고침
만료정보, 서비스 상태, 사용자 행동에 맞게 새로 고침을 조정하세요. 동일 요청은 묶고, 비활성 페이지에서 백그라운드 호출을 피하며, 대체된 검색 요청은 취소하세요.
로컬 캐시 지연은 출처 신선도 증명이 아닙니다. 오류 후에도 이전 관찰값을 오래된 것으로 명시해 보여줄 수 있으며, 출처가 stale 상태면 첫 성공 갱신 시 깨끗이 지우지 마세요.
GBFS와의 연관 이해
GBFS는 공유 이동 서비스와 그 상태를 표현합니다. 직접 통합 시 파일과 버전, 타임스탬프를 해석해야 합니다. 표준화 API면 API 계약을 쓰고, GBFS 필드를 임의로 추가하지 마세요.
GTFS, GTFS Realtime, GBFS 중 선택하기
사용자 오해 상황 테스트
실제 0, 미확인 값, 만료, 대여 비활성, 유효한 결과 후 오류 상황을 테스트하세요. 표시 시각대도 점검하세요. 긍정 집계가 ’예약됨’으로, 이용 불가가 임의 0으로 변환되어선 안 됩니다.
자주 묻는 질문
양의 수량이 도착 시 자전거 존재 보장인가요?
아닙니다. 관찰값이며, 검색과 도착 사이에 변할 수 있습니다.
null을 0으로 대체해도 되나요?
안 됩니다. null은 미확인 값, 0은 알려진 양으로 다른 의미를 가집니다.
몇 초마다 새로 고쳐야 할까요?
유효 기간, 서비스 한계, 인터페이스 필요에 맞춰 사용하세요. 임의 빈도는 출처 신선도 보장하지 않습니다.