openapi: 3.1.0
info:
  title: Dehradun Tourism Developer API (dehradun1.vercel.app)
  description: Comprehensive REST API for Dehradun tourism, destinations, cultural heritage, nature spots, spiritual landmarks, and real-time visitor metrics. Hosted on Vercel with RateLimit and versioning support.
  version: 1.0.0
  termsOfService: https://dehradun1.vercel.app/privacy
  contact:
    name: Akash Priyadarshi
    url: https://github.com/AkashPriyadarshii/dehraduntourism
    email: contact@dehradun1.vercel.app
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://dehradun1.vercel.app
    description: Production Vercel Deployment
tags:
  - name: Tourism Places
    description: Attractions, temples, natural spots, and heritage sites in Dehradun
  - name: Discovery
    description: API metadata, documentation, and directory
  - name: Analytics
    description: Visitor view metrics and traffic counter
paths:
  /api/v1:
    get:
      tags:
        - Discovery
      summary: API Root & Service Discovery
      description: Returns metadata about available API endpoints, versioning policy, documentation URLs, and service status.
      operationId: getApiRoot
      responses:
        '200':
          description: API root directory and operational metadata
          headers:
            RateLimit-Limit:
              description: Quota limit per minute window
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 99
            RateLimit-Reset:
              description: Seconds until quota window resets
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDirectoryResponse'
  /api/v1/places:
    get:
      tags:
        - Tourism Places
      summary: List and filter tourist attractions in Dehradun
      description: Retrieve a list of tourist destinations, historic landmarks, nature reserves, and monasteries in Dehradun with optional filtering by category or text search.
      operationId: getPlaces
      parameters:
        - name: category
          in: query
          required: false
          description: Filter places by destination category type
          schema:
            type: string
            enum: [nature, heritage, spiritual, institutional, recreation]
        - name: search
          in: query
          required: false
          description: Search keyword matching place name, description, or Hindi title
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of places to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          description: Pagination offset
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Successfully retrieved list of places
          headers:
            RateLimit-Limit:
              description: Quota limit per minute window
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 99
            RateLimit-Reset:
              description: Seconds until quota window resets
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacesListResponse'
        '400':
          description: Invalid query parameters supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/places/{id}:
    get:
      tags:
        - Tourism Places
      summary: Get specific place details by ID or slug
      description: Fetch detailed information for a single attraction in Dehradun by its slug (e.g., 'robbers-cave-guchhupani') or numeric index.
      operationId: getPlaceById
      parameters:
        - name: id
          in: path
          required: true
          description: The unique slug or index of the tourist place
          schema:
            type: string
      responses:
        '200':
          description: Place details found
          headers:
            RateLimit-Limit:
              description: Quota limit per minute window
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 99
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceDetailResponse'
        '404':
          description: Place not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/views:
    get:
      tags:
        - Analytics
      summary: Get site visitor traffic count
      description: Retrieve the current visitor count metrics. Pass ?action=up to increment the count.
      operationId: getViews
      parameters:
        - name: action
          in: query
          required: false
          description: Set to 'up' or 'increment' to record a new page view
          schema:
            type: string
            enum: [up, increment]
      responses:
        '200':
          description: Current view count status
          headers:
            RateLimit-Limit:
              description: Quota limit per minute window
              schema:
                type: integer
                example: 100
            RateLimit-Remaining:
              description: Remaining requests in current window
              schema:
                type: integer
                example: 99
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewCountResponse'
    post:
      tags:
        - Analytics
      summary: Increment visitor count
      description: Increment the visitor counter via standard POST request.
      operationId: incrementViews
      requestBody:
        description: Optional metadata payload for incrementing views
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncrementViewsRequest'
      responses:
        '200':
          description: View count successfully incremented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewCountResponse'
components:
  schemas:
    Place:
      type: object
      required:
        - name
        - description
        - category
      properties:
        id:
          type: string
          example: robbers-cave-guchhupani
        index:
          type: integer
          example: 1
        name:
          type: string
          example: Robber's Cave (Guchhupani)
        hindi:
          type: string
          example: गुच्चुपानी
        description:
          type: string
          example: A 600m long natural river cave formation with a waterfall.
        distance:
          type: string
          example: 8 km from city center
        entryFee:
          type: string
          example: ₹25–50
        bestTime:
          type: string
          example: Summer
        category:
          type: string
          enum: [nature, heritage, spiritual, institutional, recreation]
          example: nature
        lat:
          type: number
          format: double
          example: 30.3756
        lng:
          type: number
          format: double
          example: 78.0563
        image:
          type: string
          format: uri
          example: https://upload.wikimedia.org/wikipedia/commons/2/2e/Robber%27s_Cave_Dehradun.jpg
    PlacesListResponse:
      type: object
      required:
        - total
        - count
        - offset
        - limit
        - places
      properties:
        total:
          type: integer
          example: 17
        count:
          type: integer
          example: 17
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 50
        places:
          type: array
          items:
            $ref: '#/components/schemas/Place'
    PlaceDetailResponse:
      type: object
      required:
        - place
      properties:
        place:
          $ref: '#/components/schemas/Place'
    ViewCountResponse:
      type: object
      required:
        - count
        - action
        - timestamp
      properties:
        count:
          type: integer
          example: 2055
        action:
          type: string
          example: read
        timestamp:
          type: string
          format: date-time
          example: '2026-08-25T17:00:00.000Z'
    IncrementViewsRequest:
      type: object
      properties:
        source:
          type: string
          example: ai-agent
    ApiDirectoryResponse:
      type: object
      required:
        - name
        - version
        - status
        - endpoints
      properties:
        name:
          type: string
          example: Dehradun Tourism Public REST API
        description:
          type: string
          example: Official public developer API providing tourism data for Dehradun.
        version:
          type: string
          example: 1.0.0
        status:
          type: string
          example: operational
        documentation_url:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/docs/api
        developer_portal:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/developers
        openapi_url:
          type: string
          format: uri
          example: https://dehradun1.vercel.app/openapi.json
        endpoints:
          type: object
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          example: PLACE_NOT_FOUND
        message:
          type: string
          example: Tourist attraction with ID 'unknown-place' was not found.
        status:
          type: integer
          example: 404
        hint:
          type: string
          example: Query GET /api/places for a full list of valid places.
