openapi: 3.0.0
info:
  title: Google Events Details API
  description: |
    The Google Events Details API returns the full details of one event from Google Events, including its start and end time with time zone, description, the sites listing the event with prices where Google shows them, and the venue's rating, reviews, website and phone.

    **Cross-linking**: Pass the `event_token` of a Google Events API result as the `event_token` parameter. The venue's `data_id` can be passed as the `data_id` parameter of the Google Maps Place API.

    **Unavailable events**: When Google Events has no event for the token, such as an event that has already taken place, the response carries an `error` instead of `event`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Events Details
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["google_events_details"]
        - name: event_token
          in: query
          required: true
          description: Token of the event, taken from the event_token field of a Google Events API result
          schema:
            type: string
        - name: link
          in: query
          required: false
          description: Format of the links in `offers`. `raw` returns Google redirect links, `resolved` returns the sites' own URLs
          schema:
            type: string
            enum: ["raw", "resolved"]
            default: "raw"
      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'
        event:
          $ref: '#/components/schemas/Event'
        error:
          type: string
          description: Error message if the request failed, e.g. when Google Events has no event for the event_token
    Event:
      type: object
      required: [title, date, start_time, timezone, address, source, thumbnail, venue]
      properties:
        title:
          type: string
          description: Event title
        date:
          type: string
          description: Event date and time as Google displays it
        start_time:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?$'
          description: 'Local start of the event in ISO 8601 without an offset, as a date and time (e.g. "2026-10-17T20:00:00") or as a date alone when Google lists no time (e.g. "2026-10-17")'
        end_time:
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2})?$'
          description: 'Local end of the event in the same format as start_time (e.g. "2026-10-17T21:30:00")'
        timezone:
          type: string
          description: 'IANA time zone of start_time and end_time (e.g. "America/New_York")'
        address:
          type: string
          description: Venue name and address of the event
        description:
          type: string
          description: Event description, with line breaks kept as newlines
        source:
          type: string
          description: Domain of the website the event listing comes from
        price:
          type: string
          description: Ticket price as Google displays it
        extracted_price:
          type: number
          description: Numeric ticket price
        offers:
          type: array
          description: Sites listing the event
          items:
            $ref: '#/components/schemas/Offer'
        venue:
          $ref: '#/components/schemas/Venue'
        thumbnail:
          type: string
          description: URL of the event image
        map_image:
          type: string
          description: URL of a static map image of the venue
    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 search URL for this event
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        event_token:
          type: string
          description: Token of the requested event
        link:
          type: string
          description: Format of the links in offers
    Offer:
      type: object
      required: [seller, link]
      properties:
        seller:
          type: string
          description: Name of the site listing the event
        link:
          type: string
          description: Link to the event on the site
        price:
          type: string
          description: Ticket price on this site as Google displays it
        extracted_price:
          type: number
          description: Numeric ticket price on this site
        is_official:
          type: boolean
          description: Whether Google marks the site as the event's official site
    Venue:
      type: object
      required: [name, type, reviews, data_id]
      properties:
        name:
          type: string
          description: Venue name
        type:
          type: string
          description: Venue category
        rating:
          type: number
          description: Average venue rating out of 5
        reviews:
          type: integer
          description: Number of venue reviews
        description:
          type: string
          description: Short description of the venue
        website:
          type: string
          description: Venue website
        phone:
          type: string
          description: Venue phone number in international format
        data_id:
          type: string
          description: Google Maps identifier of the venue
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong