byom-customer-trends-api/docs/openapi.yaml

openapi: 3.0.0
info:
  title: BYOM Trends API
  version: '1.0'
  description: API for managing BYOM Trends
  contact:
    name: BYOM Support
servers:
  - url: /api/v1/trends
    description: BYOM Trends API
tags:
  - name: Trends
    description: Trend analysis operations
  - name: Social
    description: Social media profile operations
  - name: Google
    description: Google Trends operations
  - name: Suggestions
    description: Product and service suggestions based on trend analysis

paths:
  /api/v1/trends/analyze/profile/{id}:
    post:
      tags:
        - Trends
      summary: Analyze trends for a social media profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Profile ID to analyze
      responses:
        '201':
          description: Trend analysis created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendAnalysis'
        '404':
          description: Profile not found
        '500':
          description: Internal server error

  /api/v1/trends/analysis/{id}:
    get:
      tags:
        - Trends
      summary: Get trend analysis report
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Analysis ID
      responses:
        '200':
          description: Trend analysis retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendAnalysis'
        '404':
          description: Analysis not found
        '500':
          description: Internal server error

  /api/v1/trends/social/connect:
    post:
      tags:
        - Social
      summary: Connect a social media profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectProfileRequest'
      responses:
        '201':
          description: Profile connected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialProfile'
        '400':
          description: Invalid request
        '500':
          description: Internal server error

  /api/v1/trends/google/analyze:
    post:
      tags:
        - Google
      summary: Analyze Google Trends data
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleTrendsRequest'
      responses:
        '200':
          description: Analysis successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleTrendsResponse'
        '400':
          description: Invalid request
        '500':
          description: Internal server error

  /api/v1/trends/google/topics:
    get:
      tags:
        - Google
      summary: Get related topics for keywords
      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
          description: Keyword to get related topics for
      responses:
        '200':
          description: Related topics retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RelatedTopic'
        '400':
          description: Invalid request
        '500':
          description: Internal server error

  /api/v1/trends/google/regional:
    get:
      tags:
        - Google
      summary: Get regional interest data
      parameters:
        - name: keyword
          in: query
          required: true
          schema:
            type: string
          description: Keyword to get regional interest for
        - name: region
          in: query
          required: false
          schema:
            type: string
          description: Specific region to analyze
      responses:
        '200':
          description: Regional interest data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
        '400':
          description: Invalid request
        '500':
          description: Internal server error

  /api/v1/trends/google/analysis/{id}:
    get:
      tags:
        - Google
      summary: Get Google Trends analysis by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Analysis ID
      responses:
        '200':
          description: Analysis retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleTrend'
        '404':
          description: Analysis not found
        '500':
          description: Internal server error

  /api/v1/trends/social/{platform}/stats:
    get:
      tags:
        - Social
      summary: Get platform-specific statistics
      parameters:
        - name: platform
          in: path
          required: true
          schema:
            type: string
            enum: [instagram, tiktok, youtube]
          description: Social media platform
      responses:
        '200':
          description: Platform statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformStats'
        '400':
          description: Invalid platform
        '500':
          description: Internal server error

  /api/v1/trends/social/{platform}/engagement/{id}:
    get:
      tags:
        - Social
      summary: Get engagement metrics for a social profile
      parameters:
        - name: platform
          in: path
          required: true
          schema:
            type: string
            enum: [instagram, tiktok, youtube]
          description: Social media platform
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Profile ID
      responses:
        '200':
          description: Engagement metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EngagementMetrics'
        '404':
          description: Profile not found
        '500':
          description: Internal server error

  /api/v1/trends/suggestions:
    post:
      tags:
        - Suggestions
      summary: Get product suggestions based on social trends
      description: Analyzes social media trends and suggests potential products or services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetSuggestionsRequest'
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductSuggestion'
        '400':
          description: Invalid request format
        '500':
          description: Internal server error

  /api/v1/trends/suggestions/user/{user_id}:
    get:
      tags:
        - Suggestions
      summary: Get all suggestions for a user
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Suggestions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductSuggestion'

  /api/v1/trends/suggestions/{id}:
    get:
      tags:
        - Suggestions
      summary: Get a specific suggestion
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Suggestion retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSuggestion'

components:
  schemas:
    TrendAnalysis:
      type: object
      properties:
        id:
          type: string
          format: uuid
        profile_id:
          type: string
          format: uuid
        type:
          type: string
          enum: [social, google]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    SocialProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        platform:
          type: string
          enum: [instagram, tiktok, youtube]
        username:
          type: string
        profile_url:
          type: string
        follower_count:
          type: integer
          format: int64
        engagement:
          type: number
          format: float
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ConnectProfileRequest:
      type: object
      required:
        - platform
        - username
      properties:
        platform:
          type: string
          enum: [instagram, tiktok, youtube]
        username:
          type: string

    GoogleTrendsRequest:
      type: object
      required:
        - keywords
      properties:
        keywords:
          type: array
          items:
            type: string
        time_range:
          type: string
          enum: [LAST_HOUR, LAST_DAY, LAST_WEEK, LAST_MONTH]
        region:
          type: string

    GoogleTrendsResponse:
      type: object
      properties:
        results:
          type: object
          additionalProperties:
            type: integer
        related_topics:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/RelatedTopic'
        regional_interest:
          type: object
          additionalProperties:
            type: integer

    RelatedTopic:
      type: object
      properties:
        title:
          type: string
        type:
          type: string
        value:
          type: integer

    GoogleTrend:
      type: object
      properties:
        id:
          type: string
          format: uuid
        keyword:
          type: string
        interest_over_time:
          type: object
          additionalProperties:
            type: integer
        created_at:
          type: string
          format: date-time

    PlatformStats:
      type: object
      properties:
        platform:
          type: string
          enum: [instagram, tiktok, youtube]
        total_profiles:
          type: integer
        avg_engagement:
          type: number
          format: float
        trending_topics:
          type: array
          items:
            type: string

    EngagementMetrics:
      type: object
      properties:
        profile_id:
          type: string
          format: uuid
        platform:
          type: string
          enum: [instagram, tiktok, youtube]
        engagement_rate:
          type: number
          format: float
        likes:
          type: integer
        comments:
          type: integer
        shares:
          type: integer
        period:
          type: string
          enum: [daily, weekly, monthly]
        timestamp:
          type: string
          format: date-time

    GetSuggestionsRequest:
      type: object
      required:
        - user_id
        - socials
      properties:
        user_id:
          type: string
          description: ID of the user requesting suggestions
        socials:
          type: array
          description: List of social media profiles to analyze for suggestions
          items:
            $ref: '#/components/schemas/Social'

    Social:
      type: object
      required:
        - platform
        - username
      properties:
        platform:
          type: string
          enum: [instagram, tiktok, youtube]
        username:
          type: string

    ProductSuggestion:
      type: object
      properties:
        name:
          type: string
          description: Name of the suggested product or service
        description:
          type: string
          description: Short description of the product/service
        target_audience:
          type: string
          description: Description of the target market
        relevance_score:
          type: number
          format: float
          minimum: 1
          maximum: 10
          description: Score indicating how well the suggestion matches current trends
        success_factors:
          type: array
          items:
            type: string
            description: List of factors supporting the potential success

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []