openapi: 3.0.0
info:
  title: Google Events API
  description: |
    The Google Events API allows you to search for local events and retrieve detailed information including dates, locations, venues, and ticket information from Google Events search results.

    This API returns structured data about upcoming events including event details, venue information, ticket offers from various sellers, and location maps.

    **Cross-linking**: Event links can be used to view the event directly on Google. Venue links provide more information about the location where the event is held.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Events Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["google_events"]
        - name: q
          in: query
          required: true
          description: Search query for events
          schema:
            type: string
        - name: location
          in: query
          required: false
          description: Location for event search (e.g., "New York", "San Francisco,California,United States")
          schema:
            type: string
        - name: uule
          in: query
          required: false
          description: Google's encoded location parameter. Overrides the location parameter when both are provided
          schema:
            type: string
        - name: hl
          in: query
          required: false
          description: Interface language for the search results
          schema:
            type: string
            default: "en"
        - name: gl
          in: query
          required: false
          description: Country code for localizing search results
          schema:
            type: string
            default: "us"
        - name: chips
          in: query
          required: false
          description: Filter chips for refining event search results
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page number for pagination (1-based)
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        events:
          type: array
          description: Array of event results
          items:
            $ref: '#/components/schemas/Event'
        error:
          type: string
          description: Error message if the request failed
    SearchMetadata:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Google Events URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: Search query
        location:
          type: string
          description: Location parameter used
        location_used:
          type: string
          description: Actual location used by Google after resolving the location parameter
        uule:
          type: string
          description: Encoded location parameter
        hl:
          type: string
          description: Interface language
        gl:
          type: string
          description: Country code
        chips:
          type: string
          description: Filter chips
    Event:
      type: object
      required: [position, title, link, date, duration, address, location, venue, offers, event_location_map]
      properties:
        position:
          type: integer
          description: Position of the event in search results
        title:
          type: string
          description: Event title
        link:
          type: string
          description: Direct link to the event page
        date:
          type: object
          description: Event date information
          required: [day, month]
          properties:
            day:
              type: string
              description: Day of the event
            month:
              type: string
              description: Month of the event
        duration:
          type: string
          description: Duration of the event
        address:
          type: string
          description: Street address of the event
        location:
          type: string
          description: Location name or area of the event
        thumbnail:
          type: string
          description: Event thumbnail image URL
        description:
          type: string
          description: Detailed description of the event
        venue:
          type: object
          description: Venue information where the event is held
          required: [name, rating, reviews, link]
          properties:
            name:
              type: string
              description: Name of the venue
            rating:
              type: number
              format: float
              description: Venue rating
            reviews:
              type: integer
              description: Number of reviews for the venue
            link:
              type: string
              description: Link to venue information
        offers:
          type: array
          description: Ticket offers from various sellers
          items:
            type: object
            required: [seller, link, link_type]
            properties:
              seller:
                type: string
                description: Name or domain of the ticket seller
              link:
                type: string
                description: Link to purchase tickets
              link_type:
                type: string
                description: Type of link (e.g., "tickets", "more info")
        event_location_map:
          type: object
          description: Location map for the event
          required: [image, link]
          properties:
            image:
              type: string
              description: Map image URL
            link:
              type: string
              description: Link to interactive map
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong