{"openapi":"3.1.0","info":{"title":"NPS Hikes API","description":"\n    API for exploring National Park hiking trails from OpenStreetMap and USGS data sources.\n\n    See the [full project documentation](https://seanangio.github.io/nps-hikes/) for details.\n    ","contact":{"name":"NPS Hikes Project"},"license":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"version":"1.1.0"},"paths":{"/":{"get":{"tags":["Root"],"summary":"Root","description":"Root endpoint returning API information and available endpoints.\n\nReturns basic metadata about the API and links to documentation.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Root  Get"}}}}}}},"/parks":{"get":{"tags":["Parks"],"summary":"Get all parks","description":"Returns all National Parks with metadata and optional filtering.\n\n    By default, returns all parks. Use `park_code` to get a single park,\n    `state` to filter by state, `visited=true` to get only visited parks,\n    or `visited=false` to get only unvisited parks.\n    Use `visit_year` and/or `visit_month` to filter by when parks were visited.\n    Use `description=true` to include full park descriptions.","operationId":"get_all_parks_parks_get","parameters":[{"name":"description","in":"query","required":false,"schema":{"type":"boolean","description":"Include full park descriptions in the response (increases response size)","default":false,"title":"Description"},"description":"Include full park descriptions in the response (increases response size)"},{"name":"visited","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by visit status: true=visited only, false=not yet visited, omit=all parks","title":"Visited"},"description":"Filter by visit status: true=visited only, false=not yet visited, omit=all parks"},{"name":"visit_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"Filter by visit year (e.g., 2024)","title":"Visit Year"},"description":"Filter by visit year (e.g., 2024)"},{"name":"visit_month","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by visit month(s). Use month names or abbreviations (e.g., 'Oct', 'October'). Repeat for multiple months: ?visit_month=Jun&visit_month=Jul&visit_month=Aug","title":"Visit Month"},"description":"Filter by visit month(s). Use month names or abbreviations (e.g., 'Oct', 'October'). Repeat for multiple months: ?visit_month=Jun&visit_month=Jul&visit_month=Aug"},{"name":"park_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$"},{"type":"null"}],"description":"Filter by 4-character park code (e.g., 'yose')","title":"Park Code"},"description":"Filter by 4-character park code (e.g., 'yose')"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"Filter by state using 2-letter code (e.g., 'CA')","title":"State"},"description":"Filter by state using 2-letter code (e.g., 'CA')"},{"name":"boundary","in":"query","required":false,"schema":{"type":"boolean","description":"Include simplified park boundary GeoJSON in the response","default":false,"title":"Boundary"},"description":"Include simplified park boundary GeoJSON in the response"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParksResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trails":{"get":{"tags":["Trails"],"summary":"Get trails","description":"Returns hiking trails from both TNM and OSM data sources.\n\n    Combines TNM and OSM data, preferring TNM when duplicates exist (based on fuzzy name matching).\n    Supports filtering by park, state, length, source, hiking status, trail type,\n    and 3D visualization availability.","operationId":"get_trails_trails_get","parameters":[{"name":"park_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$"},{"type":"null"}],"description":"Filter by 4-character park code (e.g., 'yose')","title":"Park Code"},"description":"Filter by 4-character park code (e.g., 'yose')"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"},{"type":"null"}],"description":"Filter by state using 2-letter code (e.g., 'CA' or 'UT'). For multiple states, repeat the parameter: ?state=CA&state=OR","title":"State"},"description":"Filter by state using 2-letter code (e.g., 'CA' or 'UT'). For multiple states, repeat the parameter: ?state=CA&state=OR"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(TNM|OSM)$"},{"type":"null"}],"description":"Filter by data source ('TNM' or 'OSM')","title":"Source"},"description":"Filter by data source ('TNM' or 'OSM')"},{"name":"hiked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by hiking status. Use true to show only hiked trails, false to show only trails not yet hiked, or omit to show all trails","title":"Hiked"},"description":"Filter by hiking status. Use true to show only hiked trails, false to show only trails not yet hiked, or omit to show all trails"},{"name":"min_length","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"description":"Minimum trail length in miles (e.g., 5.0)","title":"Min Length"},"description":"Minimum trail length in miles (e.g., 5.0)"},{"name":"max_length","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":100,"minimum":0},{"type":"null"}],"description":"Maximum trail length in miles (e.g., 10.0)","title":"Max Length"},"description":"Maximum trail length in miles (e.g., 10.0)"},{"name":"trail_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by OSM highway type (e.g., 'path', 'footway', 'track')","title":"Trail Type"},"description":"Filter by OSM highway type (e.g., 'path', 'footway', 'track')"},{"name":"viz_3d","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by 3D visualization availability. Use true to show only trails with 3D viz, false to show only trails without 3D viz, or omit to show all trails","title":"Viz 3D"},"description":"Filter by 3D visualization availability. Use true to show only trails with 3D viz, false to show only trails without 3D viz, or omit to show all trails"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Number of trails per page (1-1000). Defaults to 50.","default":50,"title":"Limit"},"description":"Number of trails per page (1-1000). Defaults to 50."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of trails to skip (for pagination). Defaults to 0.","default":0,"title":"Offset"},"description":"Number of trails to skip (for pagination). Defaults to 0."},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Page number (alternative to offset). Use with page_size parameter.","title":"Page"},"description":"Page number (alternative to offset). Use with page_size parameter."},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":1000,"minimum":1},{"type":"null"}],"description":"Items per page (alternative to limit). Must be used with 'page' parameter.","title":"Page Size"},"description":"Items per page (alternative to limit). Must be used with 'page' parameter."},{"name":"geojson","in":"query","required":false,"schema":{"type":"boolean","description":"Include trail geometry GeoJSON in the response","default":false,"title":"Geojson"},"description":"Include trail geometry GeoJSON in the response"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrailsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/trails/hiked-points":{"get":{"tags":["Trails"],"summary":"Get hiked location points","description":"Returns GPS marker points from Google My Maps representing actual hikes.\n\n    Each point includes the location name, coordinates, park info, and\n    optionally the matched trail name and data source.\n\n    Use `park_code` to filter by a single park.","operationId":"get_hiked_points_trails_hiked_points_get","parameters":[{"name":"park_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$"},{"type":"null"}],"description":"Filter by 4-character park code (e.g., 'yose')","title":"Park Code"},"description":"Filter by 4-character park code (e.g., 'yose')"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HikedPointsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats":{"get":{"tags":["Stats"],"summary":"Get aggregate hiking statistics","description":"Returns aggregate statistics across all trails, including total trails,\n    total miles, average trail length, parks and states counts, source breakdown,\n    and longest/shortest trails.\n\n    Use `hiked=true` to get stats for only hiked trails (personal stats),\n    `hiked=false` for only unvisited trails, or omit for all trails.","operationId":"get_stats_stats_get","parameters":[{"name":"hiked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by hiking status: true=hiked only, false=not yet hiked, omit=all trails","title":"Hiked"},"description":"Filter by hiking status: true=hiked only, false=not yet hiked, omit=all trails"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stats/parks":{"get":{"tags":["Stats"],"summary":"Get per-park hiking statistics","description":"Returns trail statistics broken down by park, sorted by trail count descending.\n\n    Use `hiked=true` to get stats for only hiked trails per park,\n    `hiked=false` for only unvisited trails per park, or omit for all trails.","operationId":"get_park_stats_stats_parks_get","parameters":[{"name":"hiked","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by hiking status: true=hiked only, false=not yet hiked, omit=all trails","title":"Hiked"},"description":"Filter by hiking status: true=hiked only, false=not yet hiked, omit=all trails"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParkStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/parks/{park_code}/summary":{"get":{"tags":["Parks"],"summary":"Get park summary with trail statistics","description":"Returns a detailed summary for a single park combining metadata\n    (name, location, visit date) with trail statistics (total/hiked counts,\n    mileage, source breakdown, 3D visualization availability).","operationId":"get_park_summary_parks__park_code__summary_get","parameters":[{"name":"park_code","in":"path","required":true,"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$","description":"4-character lowercase park code (e.g., 'yose' for Yosemite)","examples":["yose","grca","zion"],"title":"Park Code"},"description":"4-character lowercase park code (e.g., 'yose' for Yosemite)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParkSummaryResponse"}}}},"404":{"description":"Park not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/parks/viz/us-static-park-map":{"get":{"tags":["Visualizations"],"summary":"Get static US park map","description":"Returns a PNG image showing all national parks on a US map with AK/HI insets.\n\n    Parks are color-coded by visited/unvisited status with a visit count legend.","operationId":"get_us_static_park_map_parks_viz_us_static_park_map_get","responses":{"200":{"description":"PNG image of US park map","content":{"application/json":{"schema":{}},"image/png":{}}},"404":{"description":"Visualization not available"}}}},"/parks/viz/us-interactive-park-map":{"get":{"tags":["Visualizations"],"summary":"Get interactive US park map","description":"Returns an interactive HTML map showing all national parks with boundaries and hover tooltips.\n\n    Parks are color-coded by visited/unvisited status. The map is zoomable and pannable.","operationId":"get_us_interactive_park_map_parks_viz_us_interactive_park_map_get","responses":{"200":{"description":"Interactive HTML park map","content":{"application/json":{"schema":{}},"text/html":{}}},"404":{"description":"Visualization not available"}}}},"/parks/{park_code}/viz/static-map":{"get":{"tags":["Visualizations"],"summary":"Get static trail map for a park","description":"Returns a PNG image showing all trails for the specified park on a static map.\n\n    The map displays trail routes overlaid on the park boundary, providing a visual\n    overview of the park's trail network.","operationId":"get_static_map_parks__park_code__viz_static_map_get","parameters":[{"name":"park_code","in":"path","required":true,"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$","description":"4-character lowercase park code (e.g., 'yose' for Yosemite)","examples":["yose","grca","zion"],"title":"Park Code"},"description":"4-character lowercase park code (e.g., 'yose' for Yosemite)"}],"responses":{"200":{"description":"PNG image of park trail map","content":{"application/json":{"schema":{}},"image/png":{}}},"404":{"description":"Park not found or visualization not available"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/parks/{park_code}/viz/elevation-matrix":{"get":{"tags":["Visualizations"],"summary":"Get elevation change matrix for a park","description":"Returns a PNG heatmap showing elevation changes between different trail points in the park.\n\n    The matrix visualizes elevation gain/loss patterns across the trail network,\n    helping identify challenging trail segments and elevation profiles.","operationId":"get_elevation_matrix_parks__park_code__viz_elevation_matrix_get","parameters":[{"name":"park_code","in":"path","required":true,"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$","description":"4-character lowercase park code (e.g., 'yose' for Yosemite)","examples":["yose","grca","zion"],"title":"Park Code"},"description":"4-character lowercase park code (e.g., 'yose' for Yosemite)"}],"responses":{"200":{"description":"PNG image of elevation change matrix","content":{"application/json":{"schema":{}},"image/png":{}}},"404":{"description":"Park not found or visualization not available"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/parks/{park_code}/trails/{trail_slug}/viz/3d":{"get":{"tags":["Visualizations"],"summary":"Get 3D trail visualization","description":"Returns an interactive 3D visualization of a trail with elevation data.\n\n    The visualization displays the trail's elevation profile in an interactive 3D space\n    that can be rotated, zoomed, and panned. Requires elevation data to be available.","operationId":"get_trail_3d_visualization_parks__park_code__trails__trail_slug__viz_3d_get","parameters":[{"name":"park_code","in":"path","required":true,"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[a-z]{4}$","description":"4-character lowercase park code (e.g., 'yose' for Yosemite)","examples":["yose","grca","zion"],"title":"Park Code"},"description":"4-character lowercase park code (e.g., 'yose' for Yosemite)"},{"name":"trail_slug","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[a-z0-9_-]+$","description":"URL-safe trail slug (e.g., 'mariposa_grove_trail')","examples":["mariposa_grove_trail","bright_angel_trail"],"title":"Trail Slug"},"description":"URL-safe trail slug (e.g., 'mariposa_grove_trail')"},{"name":"z_scale","in":"query","required":false,"schema":{"type":"number","maximum":20.0,"minimum":1.0,"description":"Z-axis exaggeration factor for visualization (default: 5.0)","default":5.0,"title":"Z Scale"},"description":"Z-axis exaggeration factor for visualization (default: 5.0)"}],"responses":{"200":{"description":"Interactive HTML 3D visualization","content":{"application/json":{"schema":{}},"text/html":{}}},"404":{"description":"Trail not found or elevation data not available"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/query":{"post":{"tags":["Natural Language Query"],"summary":"Ask a question about trails or parks in natural language","description":"Translates a natural language question into a structured API call\n    using a local LLM (Ollama).\n\n    Requires Ollama to be running locally with a compatible model.\n\n    **Example queries:**\n    - \"Show me trails in Yosemite\"\n    - \"What are the longest trails I've hiked?\"\n    - \"Find footway trails in California under 3 miles\"\n    - \"Which parks have I visited?\"","operationId":"natural_language_query_query_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlqRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlqResponse"}}}},"429":{"description":"Rate limit exceeded or LLM is busy"},"503":{"description":"Ollama is not running or unreachable"},"422":{"description":"Could not interpret the query"}}}},"/health":{"get":{"tags":["Health"],"summary":"Health Check","description":"Health check endpoint to verify API and database connectivity.\n\nReturns the status of the API server and database connection.\nUseful for monitoring and load balancer health checks.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Health Check Health Get"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HikedPoint":{"properties":{"id":{"type":"integer","title":"Id","description":"Unique identifier for the hiking location","examples":[1]},"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"location_name":{"type":"string","title":"Location Name","description":"Name of the hiking location","examples":["Vernal Fall"]},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"Latitude coordinate","examples":[37.7268]},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude","description":"Longitude coordinate","examples":[-119.5428]},"matched_trail_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Trail Name","description":"Name of the matched trail (if matched)","examples":["Mist Trail"]},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"Data source of the matched trail ('TNM' or 'OSM')","examples":["TNM"]}},"type":"object","required":["id","park_code","location_name"],"title":"HikedPoint","description":"Individual hiked location point from Google My Maps."},"HikedPointsResponse":{"properties":{"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Number of hiked points returned","examples":[299]},"hiked_points":{"items":{"$ref":"#/components/schemas/HikedPoint"},"type":"array","title":"Hiked Points","description":"List of hiked location points"}},"type":"object","required":["count","hiked_points"],"title":"HikedPointsResponse","description":"Response model for hiked points endpoint."},"NlqRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":3,"title":"Query","description":"Natural language question about trails or parks","examples":["Show me long trails in Yosemite","What parks have I visited?","Find hikes under 3 miles in Utah"]}},"type":"object","required":["query"],"title":"NlqRequest","description":"Request model for natural language trail/park queries."},"NlqResponse":{"properties":{"original_query":{"type":"string","title":"Original Query","description":"The original natural language query"},"interpreted_as":{"additionalProperties":true,"type":"object","title":"Interpreted As","description":"The structured parameters extracted from the query"},"function_called":{"type":"string","title":"Function Called","description":"The function that was called to answer the query"},"results":{"additionalProperties":true,"type":"object","title":"Results","description":"The API results from the dispatched function"}},"type":"object","required":["original_query","interpreted_as","function_called","results"],"title":"NlqResponse","description":"Response model for natural language queries.\n\nReturns the original query, how it was interpreted, which function\nwas called, and the results from the dispatched endpoint."},"PaginationMetadata":{"properties":{"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","description":"Number of items per page","examples":[50]},"offset":{"type":"integer","minimum":0.0,"title":"Offset","description":"Number of items skipped (starting position)","examples":[0]},"total_count":{"type":"integer","minimum":0.0,"title":"Total Count","description":"Total number of items matching the query","examples":[347]},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more pages after this one","examples":[true]},"has_prev":{"type":"boolean","title":"Has Prev","description":"Whether there are previous pages before this one","examples":[false]}},"type":"object","required":["limit","offset","total_count","has_next","has_prev"],"title":"PaginationMetadata","description":"Pagination metadata for paginated API responses.\n\nProvides information about the current page, total results,\nand navigation flags for next/previous pages.","examples":[{"has_next":true,"has_prev":false,"limit":50,"offset":0,"total_count":347}]},"Park":{"properties":{"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"Official full name of the park","examples":["Yosemite National Park"]},"states":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"States","description":"States where the park is located","examples":["CA"]},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"Latitude coordinate","examples":[37.8651]},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude","description":"Longitude coordinate","examples":[-119.5383]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"NPS website URL for the park","examples":["https://www.nps.gov/yose/index.htm"]},"designation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Designation","description":"NPS designation (e.g., 'National Park', 'National Park & Preserve')","examples":["National Park"]},"visit_month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Month","description":"Month of park visit","examples":["July"]},"visit_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visit Year","description":"Year of park visit","examples":[2023]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Park description (only included when description=true)","examples":["Not just a great valley, but a shrine to human foresight, the strength of granite..."]},"boundary":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Boundary","description":"Simplified park boundary as GeoJSON geometry (only included when boundary=true)"}},"type":"object","required":["park_code"],"title":"Park","description":"Individual park information.\n\nRepresents a single National Park with metadata.","examples":[{"full_name":"Yosemite National Park","latitude":37.8651,"longitude":-119.5383,"park_code":"yose","park_name":"Yosemite","states":"CA","url":"https://www.nps.gov/yose/index.htm","visit_month":"July","visit_year":2023}]},"ParkStats":{"properties":{"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"trail_count":{"type":"integer","minimum":0.0,"title":"Trail Count","description":"Number of trails in this park","examples":[42]},"total_miles":{"type":"number","minimum":0.0,"title":"Total Miles","description":"Total trail mileage in this park","examples":[187.3]},"avg_trail_length":{"type":"number","minimum":0.0,"title":"Avg Trail Length","description":"Average trail length in this park","examples":[4.46]}},"type":"object","required":["park_code","trail_count","total_miles","avg_trail_length"],"title":"ParkStats","description":"Statistics for a single park.","examples":[{"avg_trail_length":4.46,"park_code":"yose","park_name":"Yosemite","total_miles":187.3,"trail_count":42}]},"ParkStatsResponse":{"properties":{"park_count":{"type":"integer","minimum":0.0,"title":"Park Count","description":"Number of parks with trails","examples":[36]},"parks":{"items":{"$ref":"#/components/schemas/ParkStats"},"type":"array","title":"Parks","description":"Per-park statistics sorted by trail count descending"}},"type":"object","required":["park_count","parks"],"title":"ParkStatsResponse","description":"Per-park hiking statistics.\n\nProvides trail statistics broken down by park, sorted by trail count descending.","examples":[{"park_count":2,"parks":[{"avg_trail_length":4.46,"park_code":"yose","park_name":"Yosemite","total_miles":187.3,"trail_count":42},{"avg_trail_length":3.25,"park_code":"zion","park_name":"Zion","total_miles":48.7,"trail_count":15}]}]},"ParkSummaryResponse":{"properties":{"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name","description":"Official full name of the park","examples":["Yosemite National Park"]},"designation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Designation","description":"NPS designation","examples":["National Park"]},"states":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"States","description":"States where the park is located","examples":["CA"]},"latitude":{"anyOf":[{"type":"number","maximum":90.0,"minimum":-90.0},{"type":"null"}],"title":"Latitude","description":"Latitude coordinate","examples":[37.8651]},"longitude":{"anyOf":[{"type":"number","maximum":180.0,"minimum":-180.0},{"type":"null"}],"title":"Longitude","description":"Longitude coordinate","examples":[-119.5383]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"NPS website URL for the park","examples":["https://www.nps.gov/yose/index.htm"]},"visit_month":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Visit Month","description":"Month of park visit","examples":["July"]},"visit_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Visit Year","description":"Year of park visit","examples":[2023]},"total_trails":{"type":"integer","minimum":0.0,"title":"Total Trails","description":"Total number of deduplicated trails in this park","examples":[42]},"total_miles":{"type":"number","minimum":0.0,"title":"Total Miles","description":"Total trail mileage in this park","examples":[187.3]},"avg_trail_length":{"type":"number","minimum":0.0,"title":"Avg Trail Length","description":"Average trail length in miles","examples":[4.46]},"hiked_trails":{"type":"integer","minimum":0.0,"title":"Hiked Trails","description":"Number of trails hiked in this park","examples":[15]},"hiked_miles":{"type":"number","minimum":0.0,"title":"Hiked Miles","description":"Total miles of hiked trails in this park","examples":[67.2]},"source_breakdown":{"$ref":"#/components/schemas/SourceBreakdown","description":"Trail counts by data source (TNM vs OSM)"},"viz_3d_count":{"type":"integer","minimum":0.0,"title":"Viz 3D Count","description":"Number of trails with 3D visualization available","examples":[10]}},"type":"object","required":["park_code","total_trails","total_miles","avg_trail_length","hiked_trails","hiked_miles","source_breakdown","viz_3d_count"],"title":"ParkSummaryResponse","description":"Detailed park summary combining metadata and trail statistics.\n\nProvides a complete overview of a single park including visit info,\ntrail counts (total and hiked), mileage, source breakdown, and\n3D visualization availability.","examples":[{"avg_trail_length":4.46,"designation":"National Park","full_name":"Yosemite National Park","hiked_miles":67.2,"hiked_trails":15,"latitude":37.8651,"longitude":-119.5383,"park_code":"yose","park_name":"Yosemite","source_breakdown":{"osm":12,"tnm":30},"states":"CA","total_miles":187.3,"total_trails":42,"url":"https://www.nps.gov/yose/index.htm","visit_month":"July","visit_year":2023,"viz_3d_count":10}]},"ParksResponse":{"properties":{"park_count":{"type":"integer","minimum":0.0,"title":"Park Count","description":"Total number of parks returned","examples":[63]},"visited_count":{"type":"integer","minimum":0.0,"title":"Visited Count","description":"Number of parks that have been visited","examples":[36]},"parks":{"items":{"$ref":"#/components/schemas/Park"},"type":"array","title":"Parks","description":"List of parks"}},"type":"object","required":["park_count","visited_count","parks"],"title":"ParksResponse","description":"Response model for parks listing endpoint.\n\nContains park count, visited count, and a list of all National Parks.","examples":[{"park_count":2,"parks":[{"designation":"National Park & Preserve","full_name":"Denali National Park & Preserve","latitude":63.3334,"longitude":-150.5013,"park_code":"dena","park_name":"Denali","states":"AK","url":"https://www.nps.gov/dena/index.htm"},{"designation":"National Park","full_name":"Yosemite National Park","latitude":37.8651,"longitude":-119.5383,"park_code":"yose","park_name":"Yosemite","states":"CA","url":"https://www.nps.gov/yose/index.htm","visit_month":"July","visit_year":2023}],"visited_count":1}]},"SourceBreakdown":{"properties":{"tnm":{"type":"integer","minimum":0.0,"title":"Tnm","description":"Number of trails from The National Map","examples":[200]},"osm":{"type":"integer","minimum":0.0,"title":"Osm","description":"Number of trails from OpenStreetMap","examples":[147]}},"type":"object","required":["tnm","osm"],"title":"SourceBreakdown","description":"Count of trails by data source."},"StatsResponse":{"properties":{"total_trails":{"type":"integer","minimum":0.0,"title":"Total Trails","description":"Total number of deduplicated trails","examples":[347]},"total_miles":{"type":"number","minimum":0.0,"title":"Total Miles","description":"Total trail mileage","examples":[1523.4]},"avg_trail_length":{"type":"number","minimum":0.0,"title":"Avg Trail Length","description":"Average trail length in miles","examples":[4.39]},"parks_count":{"type":"integer","minimum":0.0,"title":"Parks Count","description":"Number of distinct parks with trails","examples":[36]},"states_count":{"type":"integer","minimum":0.0,"title":"States Count","description":"Number of distinct states covered","examples":[22]},"source_breakdown":{"$ref":"#/components/schemas/SourceBreakdown","description":"Trail counts by data source (TNM vs OSM)"},"longest_trail":{"anyOf":[{"$ref":"#/components/schemas/TrailSummary"},{"type":"null"}],"description":"The longest trail matching the filters"},"shortest_trail":{"anyOf":[{"$ref":"#/components/schemas/TrailSummary"},{"type":"null"}],"description":"The shortest trail matching the filters"}},"type":"object","required":["total_trails","total_miles","avg_trail_length","parks_count","states_count","source_breakdown"],"title":"StatsResponse","description":"Aggregate hiking statistics.\n\nProvides summary statistics across all trails, optionally filtered\nby hiking status.","examples":[{"avg_trail_length":4.39,"longest_trail":{"length_miles":14.2,"park_code":"yose","park_name":"Yosemite","trail_name":"Half Dome Trail"},"parks_count":36,"shortest_trail":{"length_miles":0.3,"park_code":"yose","park_name":"Yosemite","trail_name":"Mist Trail"},"source_breakdown":{"osm":147,"tnm":200},"states_count":22,"total_miles":1523.4,"total_trails":347}]},"Trail":{"properties":{"trail_id":{"type":"string","title":"Trail Id","description":"Unique trail identifier (permanent_identifier for TNM, osm_id for OSM)","examples":["550779"]},"trail_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trail Name","description":"Trail name (may be null for unnamed trails)","examples":["Mono Pass Trail"]},"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"states":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"States","description":"States where parent park is located (approximate - trail may not span all states)","examples":["CA"]},"source":{"type":"string","title":"Source","description":"Data source (TNM or OSM)","examples":["TNM"]},"length_miles":{"type":"number","minimum":0.0,"title":"Length Miles","description":"Trail length in miles","examples":[8.2]},"geometry_type":{"type":"string","title":"Geometry Type","description":"Geometry type (LineString or MultiLineString)","examples":["LineString"]},"highway_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Highway Type","description":"OSM highway tag (path, footway, track, etc.) - only available for OSM trails","examples":["path"]},"hiked":{"type":"boolean","title":"Hiked","description":"Whether this trail has been hiked","examples":[true]},"viz_3d_available":{"type":"boolean","title":"Viz 3D Available","description":"Whether 3D visualization is available for this trail (requires elevation data)","examples":[true]},"viz_3d_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viz 3D Slug","description":"URL-safe trail slug for 3D visualization endpoint (only present if viz_3d_available is true)","examples":["mono_pass_trail"]},"geometry":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Geometry","description":"Trail geometry as GeoJSON (only included when geojson=true)"}},"type":"object","required":["trail_id","park_code","source","length_miles","geometry_type","hiked","viz_3d_available"],"title":"Trail","description":"Individual trail information.\n\nRepresents a single hiking trail with metadata but no geometry.\nCombines data from both TNM and OSM sources.","examples":[{"geometry_type":"LineString","hiked":true,"length_miles":8.2,"park_code":"yose","park_name":"Yosemite","source":"TNM","states":"CA","trail_id":"550779","trail_name":"Mono Pass Trail","viz_3d_available":true,"viz_3d_slug":"mono_pass_trail"}]},"TrailSummary":{"properties":{"trail_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trail Name","description":"Trail name","examples":["Half Dome Trail"]},"park_code":{"type":"string","pattern":"^[a-z]{4}$","title":"Park Code","description":"4-character lowercase park code","examples":["yose"]},"park_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Park Name","description":"Short park name","examples":["Yosemite"]},"length_miles":{"type":"number","minimum":0.0,"title":"Length Miles","description":"Trail length in miles","examples":[14.2]}},"type":"object","required":["park_code","length_miles"],"title":"TrailSummary","description":"Summary of a single trail (used in stats for longest/shortest)."},"TrailsResponse":{"properties":{"trail_count":{"type":"integer","minimum":0.0,"title":"Trail Count","description":"Number of trails returned in this page","examples":[50]},"total_miles":{"type":"number","minimum":0.0,"title":"Total Miles","description":"Total trail mileage for trails in this page","examples":[342.7]},"trails":{"items":{"$ref":"#/components/schemas/Trail"},"type":"array","title":"Trails","description":"List of trails matching the query"},"pagination":{"$ref":"#/components/schemas/PaginationMetadata","description":"Pagination metadata including total count and navigation flags"}},"type":"object","required":["trail_count","total_miles","trails","pagination"],"title":"TrailsResponse","description":"Response model for all trails endpoint.\n\nContains summary statistics, a list of trails, and pagination metadata.","examples":[{"pagination":{"has_next":true,"has_prev":false,"limit":50,"offset":0,"total_count":127},"total_miles":20.5,"trail_count":2,"trails":[{"geometry_type":"LineString","hiked":true,"length_miles":14.2,"park_code":"yose","park_name":"Yosemite","source":"TNM","states":"CA","trail_id":"550779","trail_name":"Half Dome Trail","viz_3d_available":true,"viz_3d_slug":"mariposa_grove_trail"},{"geometry_type":"LineString","highway_type":"path","hiked":false,"length_miles":6.3,"park_code":"yose","park_name":"Yosemite","source":"OSM","states":"CA","trail_id":"123456789","trail_name":"Mist Trail","viz_3d_available":false}]}]},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}