AlertCamp Parks V10 API

openapi: 3.2.0
info:
  title: AlertCamp Parks V10 API
  description: Service d'alertes de disponibilité SEPAQ pour le camping au Québec
  version: 0.1.0
tags:
- name: parks-v10
paths:
  /api/v10/parks:
    get:
      tags:
      - parks-v10
      summary: List Parks
      description: List all parks (v10 — full surface incl. the v10 UseDirect states).
      operationId: list_parks_api_v10_parks_get
      parameters:
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by provider (e.g., 'sepaq', 'recreation_gov', 'california_parks', 'florida_parks', 'arizona_parks', 'nevada_parks', 'virginia_parks', 'minnesota_parks', 'wisconsin_parks', 'mississippi_parks', 'illinois_parks', 'ohio_parks', 'north_dakota_parks', 'missouri_parks', 'wyoming_parks', 'acc_huts', 'cvhs_huts', 'spearhead_huts', 'accwhistler_huts', 'accvi_huts', 'rippleridge_huts', 'kmc_huts')
          title: Provider
        description: Filter by provider (e.g., 'sepaq', 'recreation_gov', 'california_parks', 'florida_parks', 'arizona_parks', 'nevada_parks', 'virginia_parks', 'minnesota_parks', 'wisconsin_parks', 'mississippi_parks', 'illinois_parks', 'ohio_parks', 'north_dakota_parks', 'missouri_parks', 'wyoming_parks', 'acc_huts', 'cvhs_huts', 'spearhead_huts', 'accwhistler_huts', 'accvi_huts', 'rippleridge_huts', 'kmc_huts')
      - name: camp_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by camp type (e.g., 'Camping', 'Chalet', 'Backcountry', 'CanoeCamping')
          title: Camp Type
        description: Filter by camp type (e.g., 'Camping', 'Chalet', 'Backcountry', 'CanoeCamping')
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            minLength: 1
            maxLength: 100
          - type: 'null'
          description: Search parks by name
          title: Search
        description: Search parks by name
      - name: active_only
        in: query
        required: false
        schema:
          type: boolean
          description: Only return active parks
          default: true
          title: Active Only
        description: Only return active parks
      - name: has_coords
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: When true, return only parks with non-null latitude AND longitude. Used by the mobile map to skip parks that have no pin location. Leave unset for the default (include all).
          title: Has Coords
        description: When true, return only parks with non-null latitude AND longitude. Used by the mobile map to skip parks that have no pin location. Leave unset for the default (include all).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParkListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v10/parks/{park_id}:
    get:
      tags:
      - parks-v10
      summary: Get Park
      description: Get a specific park by ID (v10 — full schema, no freeze).
      operationId: get_park_api_v10_parks__park_id__get
      parameters:
      - name: park_id
        in: path
        required: true
        schema:
          type: string
          title: Park Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v10/parks/{park_id}/map-tree:
    get:
      tags:
      - parks-v10
      summary: Get Park Map Tree
      description: 'Return every non-leaf MapNode in the park''s drill-down tree.


        Identical handler to ``v9/parks/{id}/map-tree`` — the response shape is

        provider-agnostic; re-exposed so a v10 build needs no mixed-version flow.'
      operationId: get_park_map_tree_api_v10_parks__park_id__map_tree_get
      parameters:
      - name: park_id
        in: path
        required: true
        schema:
          type: string
          title: Park Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParkMapTreeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MapNodeAmenity:
      properties:
        legend_type:
          type: integer
          title: Legend Type
        x:
          type: integer
          title: X
        y:
          type: integer
          title: Y
        r:
          type: integer
          title: R
          default: 0
        g:
          type: integer
          title: G
          default: 0
        b:
          type: integer
          title: B
          default: 0
        icon_asset:
          type: string
          title: Icon Asset
          description: Filename under mobile/assets/legend_icons/ — empty when the upstream uses iconType=16 (badge-only, no glyph).
          default: ''
      type: object
      required:
      - legend_type
      - x
      - y
      title: MapNodeAmenity
      description: One amenity icon on a map (point overlay).
    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
    ParkMapTreeResponse:
      properties:
        park_id:
          type: string
          title: Park Id
        nodes:
          items:
            $ref: '#/components/schemas/MapNodeItem'
          type: array
          title: Nodes
      type: object
      required:
      - park_id
      - nodes
      title: ParkMapTreeResponse
      description: All non-leaf MapNodes belonging to a single park.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ParkListResponse:
      properties:
        parks:
          items:
            $ref: '#/components/schemas/ParkResponse'
          type: array
          title: Parks
        total:
          type: integer
          title: Total
      type: object
      required:
      - parks
      - total
      title: ParkListResponse
      description: Schema for list of parks response.
    MapNodeItem:
      properties:
        id:
          type: string
          title: Id
        park_id:
          type: string
          title: Park Id
        gtc_map_id:
          type: integer
          title: Gtc Map Id
        gtc_map_type:
          type: integer
          title: Gtc Map Type
        parent_gtc_map_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Parent Gtc Map Id
        leaf_campground_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Leaf Campground Id
          description: Campground PK when this MapNode IS a leaf — mobile uses it to fetch the leaf's full CampgroundMaps + sites and hand off to the existing SiteMapPickerScreen with labels, long-press preview, (i) legend, etc.
        is_root:
          type: boolean
          title: Is Root
          description: True for the entry-point node — typically the park-level map (matches Park.op_park_map_id).  Mobile picker opens this one by default.
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
          description: Proxied URL for the cached PNG, served from our endpoint to bypass upstream TLS chains.  Falls back to the raw upstream URL when bytes aren't cached.
        width:
          type: integer
          title: Width
        height:
          type: integer
          title: Height
        name_en:
          anyOf:
          - type: string
          - type: 'null'
          title: Name En
        name_fr:
          anyOf:
          - type: string
          - type: 'null'
          title: Name Fr
        child_links:
          items:
            $ref: '#/components/schemas/MapNodeChildLink'
          type: array
          title: Child Links
        sites:
          items:
            $ref: '#/components/schemas/MapNodeSiteDot'
          type: array
          title: Sites
          description: Site dots — populated for leaf maps that carry GTC mapResources entries.  Empty on intermediate maps.
        amenities:
          items:
            $ref: '#/components/schemas/MapNodeAmenity'
          type: array
          title: Amenities
          description: Amenity icon overlays — present on both leaf and non-leaf maps (intermediate maps still draw beach / visitor centre / etc. markers).
        amenity_legend:
          items:
            $ref: '#/components/schemas/AmenityLegendEntry'
          type: array
          title: Amenity Legend
          description: Amenity legend key (icon + name) for providers whose icons are baked into the map artwork (Alberta) — lets the root node show the same legend as its leaf maps.
      type: object
      required:
      - id
      - park_id
      - gtc_map_id
      - gtc_map_type
      - parent_gtc_map_id
      - is_root
      - width
      - height
      title: MapNodeItem
      description: A single non-leaf map node in the park's drill-down tree.
    AmenityLegendEntry:
      properties:
        label:
          type: string
          maxLength: 128
          title: Label
        icon_url:
          type: string
          maxLength: 512
          title: Icon Url
        bg_color:
          anyOf:
          - type: string
            maxLength: 9
          - type: 'null'
          title: Bg Color
      type: object
      required:
      - label
      - icon_url
      title: AmenityLegendEntry
      description: 'One row of the amenity legend key — an icon + its name.


        Used for providers whose amenity icons are baked into the map artwork

        (Alberta), so we show a "what the icons mean" list rather than

        positional markers.  ``icon_url`` proxies the icon from our DB.'
    MapNodeChildLink:
      properties:
        child_map_id:
          type: integer
          title: Child Map Id
          description: GTC mapId of the child
        x:
          anyOf:
          - type: integer
          - type: 'null'
          title: X
          description: Pixel x on the parent image
        y:
          anyOf:
          - type: integer
          - type: 'null'
          title: Y
          description: Pixel y on the parent image
        label_en:
          anyOf:
          - type: string
          - type: 'null'
          title: Label En
        label_fr:
          anyOf:
          - type: string
          - type: 'null'
          title: Label Fr
        target_kind:
          type: string
          title: Target Kind
          description: '''campground_map'' = child is a leaf zone map already exposed via the existing /campgrounds/{id}/maps endpoint (mobile hands off to the SiteMapPicker).  ''node'' = child is another MapNode in the tree (mobile drills deeper).'
        target_campground_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Campground Id
          description: Campground PK when target_kind='campground_map'.
      type: object
      required:
      - child_map_id
      - target_kind
      title: MapNodeChildLink
      description: 'Single drill-down target rendered as a click-circle on a parent

        map''s image.'
    ParkResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        provider:
          type: string
          title: Provider
          default: sepaq
        camp_types:
          items:
            type: string
          type: array
          title: Camp Types
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
        is_active:
          type: boolean
          title: Is Active
        is_hot:
          type: boolean
          title: Is Hot
          default: false
        hot_camp_types:
          items:
            type: string
          type: array
          title: Hot Camp Types
          description: Subset of camp_types that has at least one active hot_site. Used by the mobile picker / activity step in hotspot mode to show only the activity buckets that will actually trigger notifications. Empty when the park has no active hot_sites.
        latitude:
          anyOf:
          - type: number
          - type: 'null'
          title: Latitude
          description: Latitude in decimal degrees (WGS84). NULL for parks whose upstream provider doesn't expose coordinates.
        longitude:
          anyOf:
          - type: number
          - type: 'null'
          title: Longitude
          description: Longitude in decimal degrees (WGS84). NULL for parks whose upstream provider doesn't expose coordinates.
        campground_count:
          type: integer
          title: Campground Count
          description: Number of bookable areas inside this park. Powers the federated park-discovery picker's bottom-sheet metadata so the user can see park 'size' before committing to the wizard. UNCHANGED and still the TOTAL — see wilderness_count, which says how many of these are wilderness rather than campgrounds.
          default: 0
        site_count:
          type: integer
          title: Site Count
          description: 'Number of active bookable sites in this park. A park with exactly ONE (an Alpine Club of Canada hut) has nothing to choose, so the mobile wizard skips its accommodations step. Additive: older clients ignore it.'
          default: 0
        wilderness_count:
          type: integer
          title: Wilderness Count
          description: 'How many of `campground_count` are WILDERNESS rather than campgrounds — a backcountry permit or zone, which the card used to call a campground (Wichita Mountains'' ''three campgrounds'' were two campgrounds and a one-site wilderness permit). Always <= campground_count, and counted at the same level: by zone for a parks-as-campgrounds tenant, by campground otherwise, so the two numbers add up. An area holding both kinds counts as whichever it mostly is. Additive: a client that ignores it still shows the correct total.'
          default: 0
        backcountry_is_zone:
          type: boolean
          title: Backcountry Is Zone
          description: TRUE when this park's backcountry inventory is zone-quota (GTC bcat=7/13/14/17 — Egypt Lake, West Coast Trail, …) rather than the eastern per-site Backcountry-Campsite flow (bcat=5).  The two are disjoint per park (spec §8), so a single boolean is well-defined.  Drives the wizard/alert-detail backcountry EQUIPMENT picker (hidden for zone parks — zones have no equipment vocabulary, only tent-pads/party-size) so the platform-wide has_backcountry_equipment_picker isn't applied to zone parks.
          default: false
        backcountry_has_release_schedule:
          type: boolean
          title: Backcountry Has Release Schedule
          description: 'TRUE when at least one of this park''s zones publishes a per-cell quota RELEASE time, so a ''remind me before it opens'' opt-in can actually fire.  Recreation.gov''s family-B wilderness permits do (not_yet_released + release_date); its family-A permits publish nothing of the sort, and GoingToCamp publishes nothing at all.  ANY semantics, unlike backcountry_is_entry_date below: a park holding one permit of each family still shows the control, and the alert-level gate at creation refuses it for a selection that cannot honour it.  Gate the toggle on this AND the provider''s has_release_schedule.  Defaults FALSE, so a build that predates the field simply never offers the reminder.'
          default: false
        backcountry_is_entry_date:
          type: boolean
          title: Backcountry Is Entry Date
          description: 'TRUE when this park''s backcountry is ENTRY-DATE inventory and nothing else (Quetico: you reserve one entry point for your entry DATE and camp anywhere; asking for 1 night and 5 returns identical availability).  ALL semantics — a park with any per-night backcountry alongside it reads FALSE, because that part can still be sequenced.  Mobile labels the date range as ENTRY DATES and the nights stepper as TRIP LENGTH, since nights are a booking parameter here rather than an availability filter.  Server-derived for the same reason as supports_routes: which parks are entry-date is a data question that must be able to change without a mobile release.'
          default: false
        supports_routes:
          type: boolean
          title: Supports Routes
          description: 'TRUE when a multi-night ROUTE alert can be built for this park. Computed server-side from the provider''s supports_routes capability AND this park having route-capable backcountry inventory. Deliberately a PARK field rather than a client-side derivation: which parks of an enabled tenant can actually hold a route is a server decision, so widening it (say from zone-quota parks to per-site ones) ships without a mobile release. Distinct from backcountry_is_zone, which answers the unrelated question of whether to show tent pads.'
          default: false
        op_transaction_location_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Op Transaction Location Id
          description: GoingToCamp transactionLocationId for this park. Used by the mobile picker to build a per-park reservation URL (?transactionLocationId={id}) so the 'View on website' link lands with the correct park pre-selected in the dropdown. NULL for SEPAQ (different reservation flow).
        op_park_map_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Op Park Map Id
          description: GoingToCamp park-level mapId, resolved at seed time by walking the provider's map tree.  When set, the mobile picker uses it as the SPA deep-link target so the GTC reservation page lands on this park's view (?mapId={op_park_map_id}&...) instead of the All-Parks root.  NULL for SEPAQ and for any GTC park whose TL doesn't appear in the upstream mapLinks tree.
        op_resource_location_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Op Resource Location Id
          description: GoingToCamp resourceLocationId of the park's sole campground.  Populated only when the park has exactly one active campground (the parks-as-campgrounds shape — every OP park, every MB park, 114/115 BC parks, 13/34 PC parks).  The mobile picker appends ``&resourceLocationId={...}&view=map`` to the GTC deep-link URL so the SPA renders the campground map view; without it OP/BC parks land on All-Parks even when ``mapId`` is set.  NULL for multi-campground parks (most PC national parks, Wells Gray, NCC) where the user must pick a campground at the overview level.
        booking_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Booking Url
          description: Pre-filled, park-specific reservation deep link, computed server-side.  Populated only for Aspira/ReserveAmerica providers (Alberta, Saskatchewan), whose ``parkId`` is a numeric ``aspira_park_id`` the mobile client doesn't carry — so the client's ``reservation_url_template`` substitution (which fills ``{park_id}`` with the string park id) would land on the provider's homepage gate.  When set, the mobile 'View on website' link uses this verbatim.  NULL for SEPAQ/GoingToCamp, where the client builds the link from the template / op_park_map_id.
        search_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Search Score
          description: 'Set only on a ``search=`` response that fell back to typo-tolerant matching (nothing matched literally): similarity in [0.8, 1] of the park''s closest park or campground name.  NULL on every literal match.  Server search serves builds up to 1.11.x; later builds search ``campground_names`` on the device.'
        campground_names:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Campground Names
          description: Names of the park's campgrounds holding an active site, minus any that only repeat the park name.  Only with ``include_campground_names=true`` (v12 list); NULL otherwise, so every other caller's payload is unchanged.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - name
      - website_url
      - is_active
      - created_at
      - updated_at
      title: ParkResponse
      description: Schema for park response.
    MapNodeSiteDot:
      properties:
        site_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Site Id
          description: Our Site PK.  Null when the upstream marker doesn't match a Site row (typically excluded categories like group / seasonal sites that we filter at seed time but the upstream still draws on the map).
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Site number / name (e.g. 'B4-72', '142').
        x:
          type: integer
          title: X
        y:
          type: integer
          title: Y
        is_hot:
          type: boolean
          title: Is Hot
          default: false
        has_image:
          type: boolean
          title: Has Image
          description: True when the matching Site row has a cached photo — drives SiteMapPicker's long-press preview affordance.
          default: false
      type: object
      required:
      - x
      - y
      title: MapNodeSiteDot
      description: One site marker on a leaf map.