REST API Documentation for Hiking Trails
Mock REST API with 555 hiking trails across 48 contiguous US states
Note: This is a client-side mock API. The TrailsAPI class provides methods to query trail data from the JSON file.
Getting Started
Include the API script in your HTML:
<script src="./api/trails-api.js"></script>
Initialize the API:
const api = new TrailsAPI();
// Wait for trails to load
await api.loadTrails();
API Methods
1. Get All Trails
// Get all trails
const trails = api.getAllTrails();
// Filter trails
const filteredTrails = api.getAllTrails({
state: 'Virginia', // Filter by state name
difficulty: 3, // Filter by difficulty (single value or array)
difficulty: [1, 2], // Filter by multiple difficulty levels
maxCost: 10, // Maximum cost in dollars
minLength: 2, // Minimum length in miles
maxLength: 10, // Maximum length in miles
type: 'Loop', // Trail type (Loop, Out and Back, Point to Point)
tags: ['Waterfall'], // Must include at least one matching tag
search: 'falls', // Keyword search (name, description, city)
sortBy: 'length', // Sort by: name, length, difficulty, cost
sortOrder: 'asc', // 'asc' or 'desc'
limit: 10, // Number of results
offset: 0 // Pagination offset
});
2. Get Trail by ID
const trail = api.getTrailById(1);
// Returns trail object or null
3. Search Trails
const results = api.searchTrails('waterfall');
// Searches in name, description, location, and tags
4. Get Nearby Trails
const nearby = api.getNearbyTrails('Virginia', 50);
// Returns trails in the specified state
5. Get States
const states = api.getStates();
// Returns array of {state, trailCount}
6. Get Tags
const tags = api.getTags();
// Returns array of {tag, count}
7. Get Statistics
const stats = api.getStats();
// Returns: {
// totalTrails, averageLength, averageCost,
// freeTrails, difficultyDistribution, states
// }
8. Get Reviews
const reviews = api.getReviews({
trailId: 1, // Filter by trail ID (optional)
limit: 10 // Limit number of results (optional)
});
// Returns array of review objects sorted by date
9. Get Top Rated Trails
const topTrails = api.getTopRatedTrails(5);
// Returns top 5 trails sorted by rating
10. Helper Methods
// Get difficulty label from numeric value
const label = TrailsAPI.getDifficultyLabel(3);
// Returns: 'Moderate'
// Get Bootstrap badge class for difficulty
const badgeClass = TrailsAPI.getDifficultyBadgeClass(3);
// Returns: 'bg-warning text-dark'
Trail Object Structure
{
"id": 1,
"name": "Old Rag Mountain Trail",
"difficulty": "hard", // easy, moderate, hard, or numeric 0-5
"rating": 4.8, // Average user rating (0-5)
"length": 9.4, // Miles
"elevationGain": 2415, // Feet
"location": {
"city": "Syria", // City name
"state": "Virginia" // State name
},
"distanceFromUser": null, // Miles from user (calculated)
"cost": 30, // Dollars (0 = free)
"type": "Loop", // Loop, Out and Back, Point to Point
"description": "...", // Full trail description
"tags": ["Scenic Views", "Rock Scrambling", ...],
"image": "https://...", // Trail image URL
"coordinates": {
"lat": 38.4804,
"lng": -78.3075
}
}