지점 주변 정류장을 검색하려면 위도, 경도, 반경 정보를 근접 API에 전달하세요. 응답 상태와 반환된 엔티티, 커버리지 정보를 확인한 후 목록이나 지도를 표시합니다.
ROOTE 계약 roote-1.0.0에서 GET /v1/transit/nearby 경로는 인근 교통 장소를 검색합니다. 출발정보나 실시간 알림은 가져오지 않습니다. 장소 검색과 다음 도착 정보 검색은 별개의 작업입니다.
매개변수 설정하기
요청에는 위도를 나타내는 lat과 경도를 나타내는 lng를 사용합니다. lon 별칭도 계약 내에 명시되어 있습니다. radius 매개변수는 반경을 미터 단위로 나타내며, limit는 요청 결과 수를 제한합니다. modes 필터로 교통 수단 종류를 지정할 수 있습니다.
| 매개변수 | 예시 | 설명 |
|---|---|---|
| lat | 44.8378 | 검색 지점의 위도 |
| lng | -0.5792 | 검색 지점의 경도 |
| radius | 600 | 요청하는 반경 (미터) |
| limit | 10 | 요청하는 결과 제한 수 |
| modes | bus,tram | 검색 대상 교통 수단 종류 |
이 좌표는 보르도에서의 검색 예시이며, 특정 정류장을 보장하지 않습니다. 현재 경계, 필드 및 조건은 ROOTE OpenAPI 계약 를 참고하세요.
주변의 정류장을 찾아보세요.
도시나 현재 위치 주변의 등록된 정류장들을 탐색하세요. 이용 가능한 교통수단과 정보 상세도 확인할 수 있습니다.
서버 측에서 첫 요청 보내기
fetch가 제공되는 Node.js 환경을 위한 자바스크립트 예시입니다. 접근 토큰이 있다면 서버 환경변수에 보관하세요. 예시는 브라우저에 비밀값을 두지 않습니다.
async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
const url = new URL('https://api.roote.ai/v1/transit/nearby');
url.search = new URLSearchParams({
lat: '44.8378',
lng: '-0.5792',
radius: '600',
limit: '10',
modes: 'bus,tram'
}).toString();
const headers = { Accept: 'application/json' };
if (token) headers.Authorization = `Bearer ${token}`;
const response = await fetch(url, {
headers,
signal: AbortSignal.timeout(10000)
});
if (!response.ok) {
throw new Error(`Erreur HTTP ${response.status}`);
}
const data = await response.json();
if (data.contract_version !== 'roote-1.0.0') {
throw new Error('Version du contrat non reconnue');
}
if (!['success', 'empty', 'partial'].includes(data.status)) {
throw new Error('Recherche indisponible');
}
if (!Array.isArray(data.stations)) {
throw new Error('Réponse sans collection stations valide');
}
return {
status: data.status,
stations: data.stations,
lines: data.lines,
operators: data.operators,
coverage: data.coverage,
warnings: data.warnings,
attributions: data.attributions,
meta: data.meta
};
}
계약은 익명 접근 또는 토큰 방식 접근을 허용하며 해당 정책에 따릅니다. 접근 권한과 한도를 확인하세요. 올바른 HTTP 응답도 내용 검증이 필요하며, 운영 환경에서는 스키마 기반 객체 검증을 권장합니다.
엔티티와 관계 읽기
stations 컬렉션은 반환된 장소들입니다. 각 장소에 대해 id, name, entity_kind, location, distance_meters 값을 확인하세요. line_ids 와 operator_ids는 lines 및 operators 컬렉션과 연계할 수 있습니다.
지리적 거리는 그대로 표시하세요. 경로 계산 없이 도보 시간으로 변환하지 마세요. 가이드 근처 정류장 찾기 에서 실제 이동에 영향을 주는 출입 조건을 설명합니다.
알 수 없는 정보도 명시적으로 처리하세요. 계약에서 accessibility.wheelchair 값이 unknown일 수 있는데 이는 yes나 no와 다릅니다. 출발 가능 정보는 출발 목록 그 자체가 아닙니다.
목록 또는 지도 표시하기
식별자를 UI 요소 고정에, 이름을 레이블에, 위치를 위치 지정에 사용하세요. 노선은 이름 대신 참조된 ID로 연계하세요.
데이터에서 온 색상이나 이름이라도 외부 입력으로 안전성 검증 후 사용하세요. 이름은 삽입 HTML 대신 텍스트로 출력하세요.
출처 표시는 계약에 따라 필수인 경우 반드시 표시하세요.
빈 결과, 부분 응답 및 오류 처리
empty 결과는 알려진 영역에서 결과 없음 검색을 의미하며 실제로 교통이 없음을 증명하지 않습니다. partial 응답은 일부 장소와 제한사항을 포함할 수 있으니 결과와 경고를 함께 보여주세요.
coverage, warnings, meta에 적용 제한사항을 읽으세요. 잘린 목록은 완전한 커버리지를 뜻하지 않습니다. 네트워크 또는 HTTP 오류 발생 시 '사용 불가' 메시지를 보여주고 '정류장 없음'으로 대체하지 마세요.
429 코드가 나오면 재시도 지침과 서비스 헤더를 확인하세요. 반복 재시도는 피하세요.
stations, zones, platforms 구분하기
entity_kind 필드는 여러 수준의 장소를 구분합니다. 가까운 두 결과가 각각 다른 승강장이거나, 유사 이름이 다른 출처일 수 있습니다.
근접성만으로 장소를 자동 병합하지 마세요. 서비스에서 문서화된 관계와 아이덴티티를 활용하세요. 가이드 GTFS, GTFS-RT 및 GBFS 에서 데이터 맥락을 설명합니다.
운영 환경 통합 준비하기
위치 또는 필터가 의미있게 변경될 때만 검색하세요. 동일 요청을 묶고, 시간 제한을 정하며, 데이터 종류와 서비스 상태에 따른 캐시를 적용하세요.
장소 목록과 실시간 가용성은 신선도 요구 조건이 다릅니다. 빈 결과, 부분 결과, 오류 상황 모두에서 테스트해 사용자에게 안정적인 검색을 제공하세요.
도시 서비스로 검색 범위 확장
정류장과 도시 서비스는 별도의 경로를 사용합니다. 같은 지점 주변의 화장실을 검색하려면 GET /v1/services/nearby 경로에 lat와 lon, types=toilets를 전달하세요. 이 경로에 modes=toilets는 보내지 마십시오: 이 용어는 지도 URL에 속하며 서비스 필터에는 해당하지 않습니다.
다음 JavaScript 예제는 반경 600미터에 대한 Services URL을 생성합니다. 요청은 실행하지 않으며, 앞서 설명한 HTTP 및 계약 제어를 재사용하세요. 예상 컬렉션은 stations 대신 services가 됩니다. service_type, location, distance_meters 및 실제로 존재하는 속성을 유지하십시오.
REST 계약에는 toilets, drinking_water, fountain, wifi, parking, charging, aed, locker 등이 문서화되어 있습니다. MCP에서 노출하는 유형은 다를 수 있습니다. 허용되는 매개변수, 범위 및 접근 제한은 사용하는 인터페이스 스키마를 참조하십시오.
서비스의 속성은 검색 시점에 영업 여부를 보장하지 않습니다. 알 수 없는 접근성은 서비스 이용 불가능과 같지 않으며, 오류로 인한 빈 목록이 화장실의 부재를 증명하지도 않습니다. 각 종류별 데이터를 이름과 점 하나로 축소하지 말고 개별 정보를 유지하십시오.
통합 지도의 경우, 결과를 종류와 식별자와 연계하세요. Transit에서 반환된 정류장을 삭제하지 않고도 서비스를 오류로 표시할 수 있습니다. 검색은 동일 지점을 중심으로 하지만 상태와 범위는 다를 수 있습니다.
const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
lat: '44.8416106', lon: '-0.5810938',
radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());자주 묻는 질문
Nearby에서 다음 출발 정보를 제공하나요?
여기 계약에서는 제공하지 않습니다. 해당 경로는 교통 장소를 검색하며, 출발 정보는 별도 기능입니다.
오류 후 빈 목록을 보여도 되나요?
사용 불가 상태를 표시하세요. 오류가 정류장 부재를 의미하지는 않습니다.
API 토큰을 브라우저에 둘 수 있나요?
비밀값은 서버에 보관해야 합니다. 앱과 계정에 맞는 접근 모델을 사용하세요.