Yelp Events API

openapi: 3.2.0
info:
  title: Yelp Events API
  version: '1.0'
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: yelp-openapi.yml, yelp-events-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.yelp.com
  description: Yelp Fusion API base URL
- url: https://api.yelp.com/
security:
- bearerAuth: []
tags:
- name: Events
  description: Local event search and details
paths:
  /v3/events:
    get:
      tags:
      - Events
      operationId: searchEvents
      summary: Search Events
      description: Returns events based on the provided search criteria.
      parameters:
      - name: locale
        in: query
        description: Locale in the form {language}_{country}, e.g. en_US.
        schema:
          type: string
          pattern: ^[a-z]{2,3}_[A-Z]{2}$
        example: example
      - name: offset
        in: query
        description: Offset into the list of returned events.
        schema:
          type: integer
          minimum: 0
          maximum: 1000
        example: 1
      - name: limit
        in: query
        description: Number of events to return.
        schema:
          type: integer
          minimum: 0
          maximum: 50
          default: 3
        example: 1
      - name: sort_by
        in: query
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
      - name: sort_on
        in: query
        description: Field to sort events on.
        schema:
          type: string
          enum:
          - popularity
          - time_start
          default: popularity
        example: popularity
      - name: start_date
        in: query
        description: Unix timestamp lower bound for event start time.
        schema:
          type: integer
        example: 1
      - name: end_date
        in: query
        description: Unix timestamp upper bound for event start time.
        schema:
          type: integer
        example: 1
      - name: categories
        in: query
        description: Comma-delimited list of event category aliases.
        schema:
          type: string
        example: example
      - name: is_free
        in: query
        description: Filter for free events.
        schema:
          type: boolean
        example: true
      - name: location
        in: query
        description: Geographic area to search for events.
        schema:
          type: string
          minLength: 1
          maxLength: 250
        example: example
      - name: latitude
        in: query
        description: Latitude of the search center.
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
        example: 37.7867
      - name: longitude
        in: query
        description: Longitude of the search center.
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 180
        example: -122.4112
      - name: radius
        in: query
        description: Search radius in meters. Maximum 40000.
        schema:
          type: integer
          minimum: 0
          maximum: 40000
        example: 1
      - name: excluded_events
        in: query
        description: Comma-delimited list of event ids to exclude.
        schema:
          type: string
        example: example
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventSearchResponse'
              examples:
                SearchEvents200Example:
                  summary: Default searchEvents 200 response
                  x-microcks-default: true
                  value:
                    total: 240
                    events:
                    - id: gR9DTbKCON2g1Z23bWcEpQ
                      name: Ricky's Tacos
                      category: music
                      description: Live music in the heart of the Mission District.
                      time_start: '2026-07-04T19:00:00-07:00'
                      time_end: '2026-07-04T23:00:00-07:00'
                      location:
                        address1: 350 Mission St
                        address2: ''
                        address3: ''
                        city: San Francisco
                        state: CA
                        zip_code: '94105'
                        country: US
                        display_address: {}
                        cross_streets: example
                      latitude: 37.7867
                      longitude: -122.4112
                      image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
                      event_site_url: https://www.yelp.com/events/san-francisco-summer-music-festival
                      is_free: true
                      is_canceled: false
                      is_official: true
                      attending_count: 312
                      interested_count: 1024
                      cost: 0
                      cost_max: 0
                      tickets_url: https://www.yelp.com/events/tickets/abc123
                      business_id: gR9DTbKCON2g1Z23bWcEpQ
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api.yelp.com
      description: Yelp Fusion API base URL
  /v3/events/{event_id}:
    get:
      tags:
      - Events
      operationId: getEvent
      summary: Get Event Details
      description: Returns details for a single event by id.
      parameters:
      - name: event_id
        in: path
        required: true
        description: The id of the event to retrieve.
        schema:
          type: string
        example: example
      - name: locale
        in: query
        description: Locale in the form {language}_{country}, e.g. en_US.
        schema:
          type: string
          pattern: ^[a-z]{2,3}_[A-Z]{2}$
        example: example
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
              examples:
                GetEvent200Example:
                  summary: Default getEvent 200 response
                  x-microcks-default: true
                  value:
                    id: gR9DTbKCON2g1Z23bWcEpQ
                    name: Ricky's Tacos
                    category: music
                    description: Live music in the heart of the Mission District.
                    time_start: '2026-07-04T19:00:00-07:00'
                    time_end: '2026-07-04T23:00:00-07:00'
                    location:
                      address1: 350 Mission St
                      address2: ''
                      address3: ''
                      city: San Francisco
                      state: CA
                      zip_code: '94105'
                      country: US
                      display_address:
                      - example
                      cross_streets: example
                    latitude: 37.7867
                    longitude: -122.4112
                    image_url: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
                    event_site_url: https://www.yelp.com/events/san-francisco-summer-music-festival
                    is_free: true
                    is_canceled: false
                    is_official: true
                    attending_count: 312
                    interested_count: 1024
                    cost: 0
                    cost_max: 0
                    tickets_url: https://www.yelp.com/events/tickets/abc123
                    business_id: gR9DTbKCON2g1Z23bWcEpQ
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: https://api.yelp.com
      description: Yelp Fusion API base URL
  /v3/events/featured:
    get:
      summary: Featured Event
      tags:
      - Events
      description: This endpoint returns the featured event for a given location. Featured events are chosen by Yelp's community managers.
      operationId: v3_featured_event
      parameters:
      - $ref: '#/paths/~1v3~1events/get/parameters/10'
        in: query
        description: 'Required if either *latitude* or *longitude* is not provided.

          This string indicates the geographic area to be used when searching for events.

          Examples: "New York City", "NYC", "350 5th Ave, New York, NY 10118".

          Events returned in the response may not be strictly within the specified location.

          '
        required: false
      - $ref: '#/paths/~1v3~1events/get/parameters/11'
        in: query
        description: Required, if _location_ is not provided. Latitude of the location to search from. If latitude is provided, longitude is required too.
        required: false
      - $ref: '#/paths/~1v3~1events/get/parameters/12'
        in: query
        description: Required if _location_ is not provided. Longitude of the location to search from. If longitude is provided, latitude is required too.
        required: false
      - $ref: '#/paths/~1v3~1events/get/parameters/0'
        in: query
        required: false
      responses:
        '200':
          description: A featured event was returned.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - time_start
                properties:
                  id:
                    description: Unique ID of the event.
                    type: string
                  name:
                    description: Name of the event.
                    type: string
                    nullable: true
                  description:
                    description: Description excerpt of this event.
                    type: string
                    nullable: true
                  business_id:
                    description: Yelp Business ID of this event. No ID is returned if a business is not associated with an event.
                    type: string
                    nullable: true
                  category:
                    description: The category of the event.
                    type: string
                    nullable: true
                  cost:
                    description: Cost of attending the event.
                    type: number
                    nullable: true
                  cost_max:
                    description: Maximum cost of attending the event.
                    type: number
                    nullable: true
                  event_site_url:
                    description: Yelp page of the event.
                    type: string
                    nullable: true
                  image_url:
                    description: Yelp image URL of the event.
                    type: string
                    nullable: true
                  tickets_url:
                    description: URL to buy tickets for the event.
                    type: string
                    nullable: true
                  attending_count:
                    description: Number of Yelp users attending the event.
                    type: integer
                  interested_count:
                    description: Number of Yelp users interested in attending the event.
                    type: integer
                  is_canceled:
                    description: Whether the event is canceled.
                    type: boolean
                  is_free:
                    description: Whether the event is free.
                    type: boolean
                  is_official:
                    description: Whether the event is created by a Yelp community manager.
                    type: boolean
                  location:
                    description: Location object of the event. Includes address, city, state, zip code and country.
                    nullable: true
                    type: object
                    properties:
                      address1:
                        type: string
                        description: Street address of the event.
                        nullable: true
                      address2:
                        type: string
                        description: Street address of the event, continued.
                        nullable: true
                      address3:
                        type: string
                        description: Street address of the event, continued.
                        nullable: true
                      city:
                        type: string
                        description: City of the event.
                        nullable: true
                      state:
                        type: string
                        description: State of the event.
                        nullable: true
                      zip_code:
                        type: string
                        description: Zip code of the event.
                        nullable: true
                      country:
                        type: string
                        description: The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of the location of the event. Country the event is taking place in.
                        nullable: true
                      display_address:
                        description: Array of strings that if organized vertically give an address that is in the standard address format for the event's country.
                        type: array
                        items:
                          type: string
                        nullable: true
                      cross_streets:
                        type: string
                        description: Cross streets of this address
                        nullable: true
                  latitude:
                    description: Latitude of the event location.
                    type: number
                    format: float
                    nullable: true
                  longitude:
                    description: Longitude of the event location.
                    type: number
                    format: float
                    nullable: true
                  time_start:
                    description: Time the event starts. Returns date and time in ISO 8601 format.
                    type: string
                  time_end:
                    description: Time the event ends. Returns date and time in ISO 8601 format.
                    type: string
                    nullable: true
              examples:
                Result:
                  value:
                    id: austin-rsvps-closed-yelp-austins-backyard-blowout
                    category: music
                    cost: null
                    cost_max: null
                    description: As is always the case, when we don't want rain, we get it. Don't worry though. Yelp's gotcha covered (literally.) Both parties will be tented up and we're...
                    event_site_url: https://www.yelp.com/events/austin-rsvps-closed-yelp-austins-backyard-blowout?adjust_creative=Ey_LbvkpsGAECYM_cP_3Jw&utm_campaign=yelp_api_v3&utm_medium=api_v3_event_search&utm_source=Ey_LbvkpsGAECYM_cP_3Jw
                    attending_count: 1
                    image_url: https://s3-media3.fl.yelpcdn.com/ephoto/B9oMfBlHwU_8oSe7blx_Lw/o.jpg
                    interested_count: 1890
                    is_canceled: false
                    is_free: true
                    is_official: false
                    latitude: 30.2844663602444
                    longitude: -97.7175722159386
                    name: 'RSVPs Closed: Yelp Austin''s Backyard Blowout'
                    tickets_url: null
                    time_end: '2012-03-16T18:00:00-05:00'
                    time_start: '2012-03-16T14:00:00-05:00'
                    location:
                      address1: 2 Manor St
                      address2: ''
                      address3: ''
                      city: Austin
                      zip_code: '78732'
                      country: US
                      state: TX
                      display_address:
                      - 2 Manor St
                      - Austin, TX 78732
                      cross_streets: ''
                    business_id: the-vortex-austin-2
        '400':
          $ref: '#/paths/~1v3~1events/get/responses/400'
        '401':
          $ref: '#/paths/~1v3~1events/get/responses/401'
        '403':
          description: The API key provided is not currently able to query this endpoint.
          $ref: '#/paths/~1v3~1events/get/responses/403'
        '404':
          $ref: '#/paths/~1v3~1events/get/responses/404'
        '413':
          $ref: '#/paths/~1v3~1events/get/responses/413'
        '429':
          $ref: '#/paths/~1v3~1events/get/responses/429'
        '500':
          $ref: '#/paths/~1v3~1events/get/responses/500'
        '503':
          $ref: '#/paths/~1v3~1events/get/responses/503'
    servers:
    - url: https://api.yelp.com/
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
              e.g. VALIDATION_ERROR.: null
            description:
              type: string
              description: Human-readable error description.
    EventSearchResponse:
      type: object
      properties:
        total:
          type: integer
          example: 240
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Event:
      type: object
      properties:
        id:
          type: string
          example: gR9DTbKCON2g1Z23bWcEpQ
        name:
          type: string
          example: Ricky's Tacos
        category:
          type: string
          example: music
        description:
          type: string
          example: Live music in the heart of the Mission District.
        time_start:
          type: string
          example: '2026-07-04T19:00:00-07:00'
        time_end:
          type: string
          example: '2026-07-04T23:00:00-07:00'
        location:
          $ref: '#/components/schemas/Location'
        latitude:
          type: number
          format: double
          example: 37.7867
        longitude:
          type: number
          format: double
          example: -122.4112
        image_url:
          type: string
          format: uri
          example: https://s3-media0.fl.yelpcdn.com/bphoto/abc123/o.jpg
        event_site_url:
          type: string
          format: uri
          example: https://www.yelp.com/events/san-francisco-summer-music-festival
        is_free:
          type: boolean
          example: true
        is_canceled:
          type: boolean
          example: false
        is_official:
          type: boolean
          example: true
        attending_count:
          type: integer
          example: 312
        interested_count:
          type: integer
          example: 1024
        cost:
          type:
          - number
          - 'null'
          format: float
          example: 0
        cost_max:
          type:
          - number
          - 'null'
          format: float
          example: 0
        tickets_url:
          type: string
          format: uri
          example: https://www.yelp.com/events/tickets/abc123
        business_id:
          type:
          - string
          - 'null'
          example: gR9DTbKCON2g1Z23bWcEpQ
    Location:
      type: object
      properties:
        address1:
          type: string
          example: 350 Mission St
        address2:
          type:
          - string
          - 'null'
          example: ''
        address3:
          type:
          - string
          - 'null'
          example: ''
        city:
          type: string
          example: San Francisco
        state:
          type: string
          example: CA
        zip_code:
          type: string
          example: '94105'
        country:
          type: string
          example: US
        display_address:
          type: array
          items:
            type: string
        cross_streets:
          type: string
          example: example
  responses:
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Yelp Fusion API key passed as a bearer token in the Authorization header.
x-refined-from:
- yelp-openapi.yml
- yelp-events-api-openapi.yml
x-generated-from: https://docs.developer.yelp.com/reference
x-generated-by: api-evangelist-pipeline-2026-06