openapi: 3.1.0
info:
  title: LonelyRoad Recommendations API
  version: 1.0.0
  description: |
    A read-only API that returns nearby travelers, activities, events, and places to help you meet other travelers.

    **Perfect for:**
    - AI assistants and chatbots
    - Travel planning tools
    - Location-based recommendations

    **Rate Limits:** Fair use policy - max 100 requests per minute per IP
  contact:
    name: LonelyRoad Support
    url: https://lonelyroad.app
    email: support@lonelyroad.app
  license:
    name: Proprietary
    url: https://lonelyroad.app/terms-of-service

servers:
  - url: https://lonelyroad.app/api/v1
    description: Production API

paths:
  /recommendations:
    get:
      summary: Meet travelers nearby
      description: |
        Returns nearby travelers, activities, events, and places to help you meet other travelers.
        Includes active travelers, upcoming meetups, local events, and popular spots where travelers gather.

        **Quick Start:**
        ```bash
        curl "https://lonelyroad.app/api/v1/recommendations?lat=38.7223&lon=-9.1393&radius=5"
        ```

        Response < 2s, no auth required.
      operationId: getRecommendations
      tags:
        - Recommendations
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude coordinate
          schema:
            type: number
            format: double
            minimum: -90
            maximum: 90
          example: 38.7223

        - name: lon
          in: query
          required: true
          description: Longitude coordinate
          schema:
            type: number
            format: double
            minimum: -180
            maximum: 180
          example: -9.1393

        - name: radius
          in: query
          required: false
          description: Search radius in kilometers
          schema:
            type: number
            format: double
            minimum: 0.1
            maximum: 50
            default: 10
          example: 5

        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 15
          example: 15

      responses:
        '200':
          description: Successful response with recommendations
          content:
            application/json:
              schema:
                type: object
                properties:
                  location:
                    type: object
                    properties:
                      lat:
                        type: number
                        example: 38.7223
                      lon:
                        type: number
                        example: -9.1393
                      radius:
                        type: number
                        example: 5
                  count:
                    type: integer
                    description: Number of suggestions returned
                    example: 12
                  suggestions:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum: [person, activity, event, place]
                          description: Type of recommendation
                          example: activity
                        title:
                          type: string
                          description: Short title or name
                          example: "Coffee & Coworking Meetup"
                        icon:
                          type: string
                          description: Emoji icon representing the item
                          example: "☕"
                        why:
                          type: string
                          description: Why this is relevant (distance, type, etc.)
                          example: "John is organizing this 1.2km away"
                        start_time:
                          type: string
                          format: date-time
                          description: When the activity/event starts (if applicable)
                          nullable: true
                          example: "2025-11-12T14:00:00Z"
                        venue:
                          type: string
                          description: Venue name (for events)
                          nullable: true
                          example: "Café Culture"
                        description:
                          type: string
                          description: Short description (for places)
                          nullable: true
                          example: "Popular coworking cafe with great vibes"
                        distance_km:
                          type: number
                          format: double
                          description: Distance in kilometers from your location
                          example: 1.2
                        deep_link:
                          type: string
                          format: uri
                          description: Universal link to open this item in LonelyRoad app
                          example: "https://lonelyroad.app/open?type=activity&id=abc123"
                  _meta:
                    type: object
                    properties:
                      generated_at:
                        type: string
                        format: date-time
                        example: "2025-11-12T10:30:00Z"
                      api_version:
                        type: string
                        example: "v1"
              examples:
                lisbon:
                  summary: Example response for Lisbon
                  value:
                    location:
                      lat: 38.7223
                      lon: -9.1393
                      radius: 5
                    count: 3
                    suggestions:
                      - type: "activity"
                        title: "Walking Tour of Alfama"
                        icon: "🚶"
                        why: "Maria is organizing this 1.2km away"
                        start_time: "2025-11-12T14:00:00Z"
                        distance_km: 1.2
                        deep_link: "https://lonelyroad.app/open?type=activity&id=abc123"
                      - type: "person"
                        title: "João, 28 nearby"
                        icon: "👤"
                        why: "João is exploring 0.8km away"
                        distance_km: 0.8
                        deep_link: "https://lonelyroad.app/open?type=person&id=user456"
                      - type: "place"
                        title: "TimeOut Market"
                        icon: "🍽️"
                        why: "Food hall with Social, Party vibes - rated 4.5/5"
                        description: "Popular food market with communal seating..."
                        distance_km: 1.5
                        deep_link: "https://lonelyroad.app/open?type=place&id=place789"
                    _meta:
                      generated_at: "2025-11-12T10:30:00Z"
                      api_version: "v1"

        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Invalid coordinates. Provide lat and lon as numbers."

        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Internal server error"
                  message:
                    type: string
                    example: "Database connection failed"

components:
  schemas:
    Suggestion:
      type: object
      required:
        - type
        - title
        - icon
        - why
        - distance_km
        - deep_link
      properties:
        type:
          type: string
          enum: [person, activity, event, place]
        title:
          type: string
        icon:
          type: string
        why:
          type: string
        start_time:
          type: string
          format: date-time
          nullable: true
        venue:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        distance_km:
          type: number
        deep_link:
          type: string
          format: uri

tags:
  - name: Recommendations
    description: Get nearby travelers, activities, events, and places