swagger: "2.0"
schemes:
  - https
host: api2.lotadata.com
basePath: /v2
info:
  description: Access the most exhaustive, accurate and up-to-date collection of global and hyper-local geocoded events and activities across a wide range of categories and genres
  title: LotaData
  version: 2.0.0
  x-apisguru-categories:
    - location
  x-logo:
    backgroundColor: "#FFFFFF"
    url: https://pbs.twimg.com/profile_images/664666044754079744/OtP5eqwm_400x400.png
  x-origin:
    - format: swagger
      url: https://developers.lotadata.com/swagger/spec/apiv2.json
      version: "2.0"
  x-providerName: lotadata.com
produces:
  - application/json
securityDefinitions:
  api_key:
    description: Your API key
    in: query
    name: api_key
    type: apiKey
security:
  - api_key: []
paths:
  /events:
    get:
      parameters:
        - collectionFormat: multi
          description: List of required EventCategory ids (Tier 1)
          in: query
          items:
            type: string
          name: category
          type: array
        - description: List of required activity type ids (compliment to category)
          in: query
          name: activity
          type: string
        - description: List of required ambience ids
          in: query
          name: ambience
          type: string
        - description: List of required genre ids
          in: query
          name: genre
          type: string
        - description: Matching on event and place names
          in: query
          name: name
          type: string
        - description: Text query matching titles, description, various text, tags, category
          in: query
          name: q
          type: string
        - description: Start on or after date specified (2015-10-16)
          in: query
          name: from_day
          required: false
          type: string
        - description: Start on or before date specified (2015-10-16)
          in: query
          name: to_day
          required: false
          type: string
        - description: Min capacity at location
          format: integer
          in: query
          name: capacity_min
          required: false
          type: number
        - description: Min capacity at location
          format: integer
          in: query
          name: capacity_max
          required: false
          type: number
        - description: latitude,longitude of the origin point
          in: query
          name: center
          type: string
        - description: Distance from origin in meters
          in: query
          name: radius
          type: integer
        - collectionFormat: multi
          description: Corner of a bounding box (lat,lng). Requires 0 or 2 pairs
          in: query
          items:
            type: string
          name: bbox
          required: false
          type: array
        - collectionFormat: multi
          description: Closed custom polygon. Ordered list of lat,lng pairs
          in: query
          items:
            type: string
          name: polygon
          required: false
          type: array
        - description: Search within specified geopolitical place id
          in: query
          name: within
          required: false
          type: string
        - description: Return results starting at specified offset
          in: query
          name: offset
          type: integer
        - description: Max results to return
          in: query
          name: limit
          type: integer
        - default: context
          description: Return results starting at specified offset (summary, context, detail)
          enum:
            - summary
            - detail
            - context
            - minicontext
          in: query
          name: fieldset
          required: true
          type: string
      responses:
        "200":
          description: List of matching events
          schema:
            $ref: "#/definitions/EventsSearchResponse"
        "400":
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Find event occurrences in the area. Returns results at specific place and time, event groups are expanded for every occurrence.
      tags:
        - Events
  "/events/{id}":
    get:
      parameters:
        - description: event @id
          in: path
          name: id
          required: true
          type: string
        - default: summary
          enum:
            - summary
            - detail
            - context
            - minicontext
          in: query
          name: fieldset
          type: string
      responses:
        "200":
          description: Requested event
          schema:
            $ref: "#/definitions/EventOccurenceDetail"
        "404":
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Get Specific event details.
      tags:
        - Events
  /places:
    get:
      parameters:
        - collectionFormat: multi
          description: List of required PlaceCategory ids (Tier 1)
          in: query
          items:
            type: string
          name: category
          type: array
        - collectionFormat: multi
          description: List of required PlaceFunction ids (Tier 2)
          in: query
          items:
            type: string
          name: function
          type: array
        - description: List of required ambience ids
          in: query
          items:
            type: string
          name: ambience
          type: array
        - description: List of required tags
          in: query
          items:
            type: string
          name: tag
          type: array
        - description: Specific PlaceType to return
          in: query
          name: type
          type: string
        - description: Match on place names
          in: query
          name: name
          type: string
        - description: Require an exact name match
          in: query
          name: exact
          type: boolean
        - description: Min capacity at location
          format: integer
          in: query
          name: capacity_min
          required: false
          type: number
        - description: Min capacity at location
          format: integer
          in: query
          name: capacity_max
          required: false
          type: number
        - description: Address of the place or street component of the address
          in: query
          name: street
          type: string
        - description: city, town, or neighborhood of the place
          in: query
          name: locality
          type: string
        - description: region or state
          in: query
          name: region
          type: string
        - description: Postal or zip code
          in: query
          name: postal_code
          type: string
        - description: country component of the address
          in: query
          name: country
          type: string
        - description: latitude,longitude of the origin point
          in: query
          name: center
          type: string
        - description: Distance from origin in meters
          in: query
          name: radius
          type: integer
        - collectionFormat: multi
          description: Corner of a bounding box (lat,lng). Requires 0 or 2 pairs
          in: query
          items:
            type: string
          name: bbox
          required: false
          type: array
        - collectionFormat: multi
          description: Closed custom polygon. Ordered list of lat,lng pairs
          in: query
          items:
            type: string
          name: polygon
          required: false
          type: array
        - description: Search within specified geopolitical place id
          in: query
          name: within
          required: false
          type: string
        - description: Return results starting at specified offset
          in: query
          name: offset
          type: integer
        - description: Max results to return
          in: query
          name: limit
          type: integer
        - default: context
          description: Return results starting at specified offset (summary, context, detail)
          enum:
            - summary
            - detail
            - context
          in: query
          name: fieldset
          required: true
          type: string
      responses:
        "200":
          description: List of matching events
          schema:
            $ref: "#/definitions/PlacesSearchResponse"
        "400":
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Venues, landmarks, regions, these are all places to search.
      tags:
        - Places
  "/places/{id}":
    get:
      parameters:
        - description: place @id
          in: path
          name: id
          required: true
          type: string
        - default: summary
          enum:
            - summary
            - detail
            - context
            - minicontext
          in: query
          name: fieldset
          type: string
      responses:
        "200":
          description: Requested place
          schema:
            $ref: "#/definitions/PlaceDetail"
        "404":
          description: Unexpected error
          schema:
            $ref: "#/definitions/Error"
      summary: Get specific place details
      tags:
        - Places
definitions:
  Address:
    description: Physical world addresss
    properties:
      country:
        type: string
      formatted:
        description: Address formatted for display as a single string
        type: string
      locality:
        description: City or town
        type: string
      postalCode:
        type: string
      region:
        type: string
      street:
        description: Street portion of the address, may sometimes be a common name of the place
        type: string
      unit:
        type: string
  ContactDetail:
    properties:
      displayPhone:
        type: string
      email:
        type: string
      facebookUrl:
        type: string
      instagramName:
        type: string
      lastfmUrl:
        type: string
      soundcloudUrl:
        type: string
      spotifyUrl:
        type: string
      twitterName:
        type: string
      url:
        type: string
      youtubeUrl:
        type: string
  Error:
    properties:
      cause:
        properties:
          expected:
            type: string
          path:
            type: string
          rule:
            type: string
          value:
            type: string
      message:
        type: string
      status:
        format: int32
        type: integer
      tracking:
        properties:
          id:
            type: string
          session:
            type: string
  EventOccurenceDetail:
    description: Event Occurrence Detail limited to requested fieldset.
    properties:
      "@id":
        description: Unique event id
        type: string
      "@type":
        description: Type of occurrence. You will usually see Organized as the type for most events. While Virtual events will get their own Virtual type.
        enum:
          - Organized
          - Screening
          - Environmental
          - Virtual
        type: string
      activity:
        description: Associated ActivityType entries
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      ambience:
        description: expected mood and feel of the event
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      at:
        $ref: "#/definitions/PlaceReference"
        description: Reference to the location where event takes place
      awayTeam:
        $ref: "#/definitions/FeatureReference"
        description: other SportsTeam playing
      category:
        description: Associated EventCategory. May be multiple, such as Charity Music event
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      contactPoint:
        $ref: "#/definitions/ContactDetail"
        description: Social and contact references
      description:
        description: Full description in plain text
        type: string
      doorTime:
        description: Time when the admission starts
        format: date-time
        type: string
      duration:
        description: Duration of the event in ISO-8601 format (PT45M) - 45 minutes
        type: string
      endApprox:
        description: endDate is approximated based on historical data
        type: boolean
      endDate:
        description: Time when the event ends, if known
        format: date-time
        type: string
      extTaxonomy:
        description: extended taxonomy such as IAB and Google AdWords
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      genre:
        description: applicable Genres. (Tier 2 taxonomy). May include related genres from categories, not deemed as primary
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      headline:
        description: Optional short description in plain text
        type: string
      homeTeam:
        $ref: "#/definitions/FeatureReference"
        description: SportsTeam playing at home field
      htmlDescription:
        description: Full description with HTML formatting, where available
        type: string
      image:
        $ref: "#/definitions/ImageMeta"
        description: Primary image
      inLanguage:
        $ref: "#/definitions/FeatureReference"
        description: Primary language of the event
      name:
        description: Name of the event in plain text
        type: string
      noTime:
        description: Specific time of the event is unknown. (shown only when true)
        type: boolean
      offers:
        description: Ticketing options
        items:
          $ref: "#/definitions/TicketOffer"
        type: array
      onDemand:
        description: This event can start at any time during specified window
        type: boolean
      performer:
        description: List of Personas significant for this event
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      photo:
        description: Primary image
        items:
          $ref: "#/definitions/ImageMeta"
        type: array
      startDate:
        description: Time when the event starts
        format: date-time
        type: string
      superEvent:
        $ref: "#/definitions/OccurrenceReference"
        description: Parent id, if this event is part of a series of a group
      updated:
        description: Timestamp of last modification (UTC)
        format: date-time
        type: string
      url:
        description: Primary url for published event
        type: string
      workPerformed:
        description: Subject matter of the event
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
  EventsQuery:
    description: Specific filters understood and executed for this query. If your parameter is not visible here, then consult the documentation for correct usage.
    properties:
      activity:
        description: required activity types
        items:
          type: string
        type: array
      category:
        description: required categories
        items:
          type: string
        type: array
      limit:
        description: maximum number of matches to return
        type: integer
  EventsSearchResponse:
    properties:
      events:
        items:
          $ref: "#/definitions/EventOccurenceDetail"
        type: array
      query:
        $ref: "#/definitions/EventsQuery"
      stats:
        $ref: "#/definitions/SearchStatsMetaResult"
  FeatureReference:
    description: Identifier for a Feature
    properties:
      "@id":
        description: Feature id
        type: string
      "@type":
        description: Type of specific feature or Taxonomy node such as EventCategory, SportsTeam, Persona.
        type: string
      name:
        description: Display name of the feature
        type: string
  GeoJsonObject:
    description: Shape defined per GeoJSON spec
  GeoPt:
    properties:
      lat:
        type: number
      lon:
        type: number
  ImageMeta:
    description: Image meta data
    properties:
      "@id":
        type: string
      caption:
        type: string
      height:
        type: integer
      url:
        type: string
      width:
        type: integer
  OccurrenceReference:
    properties:
      "@id":
        type: string
      name:
        type: string
      startDate:
        description: Time when the event starts
        format: date-time
        type: string
  PlaceDetail:
    allOf:
      - $ref: "#/definitions/PlaceReference"
    properties:
      ambience:
        description: expected mood and feel of the event
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      category:
        description: Associated PlaceCategory. May be multiple (Tier 1)
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      contact:
        $ref: "#/definitions/ContactDetail"
      function:
        description: PlaceFunction. (Tier 2 taxonomy)
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
      openingHours:
        items:
          $ref: "#/definitions/Timeframe"
        type: array
      photo:
        items:
          $ref: "#/definitions/ImageMeta"
        type: array
  PlaceReference:
    description: Unique Location
    properties:
      "@id":
        type: string
      "@type":
        description: Type of place where Place is a physical address, LocalBusiness is any type of comercial property, AdministrativeArea is a political or colloquial area, and Virtual is out of this world
        enum:
          - Place
          - LocalBusiness
          - AdministrativeArea
          - TouristAttraction
          - Landform
          - LandmarksOrHistoricalBuildings
          - Residence
          - Virtual
        type: string
      address:
        $ref: "#/definitions/Address"
        description: Address of the physical place
      geo:
        $ref: "#/definitions/GeoPt"
      geometry:
        $ref: "#/definitions/GeoJsonObject"
      location:
        $ref: "#/definitions/VirtualLocation"
        description: applies to Virtual places
      logo:
        $ref: "#/definitions/ImageMeta"
      name:
        type: string
      tag:
        items:
          $ref: "#/definitions/FeatureReference"
        type: array
  PlacesQuery:
    description: Specific filters understood and executed for this query. If your parameter is not visible here, then consult the documentation for correct usage.
    properties:
      address:
        $ref: "#/definitions/Address"
        description: Address filter
      category:
        description: required categories
        items:
          type: string
        type: array
      limit:
        description: maximum number of matches to return
        type: integer
  PlacesSearchResponse:
    properties:
      places:
        items:
          $ref: "#/definitions/PlaceDetail"
        type: array
      query:
        $ref: "#/definitions/PlacesQuery"
      stats:
        $ref: "#/definitions/SearchStatsMetaResult"
  SearchStatsMetaResult:
    description: Shows invocation details about the query. Running query again, could produce different results
    properties:
      count:
        description: Total matches for the query
        type: integer
      fieldset:
        description: Specific fields returned by this query
        type: string
      runtime:
        description: Server side run time in msec for this request
        type: integer
  TicketOffer:
    properties:
      availability:
        enum:
          - Discontinued
          - InStock
          - InStoreOnly
          - LimitedAvailability
          - OnlineOnly
          - OutOfStock
          - PreOrder
          - SoldOut
        type: string
      category:
        enum:
          - primary
          - secondary
          - presale
          - member
          - premium
          - unknown
        type: string
      donation:
        type: boolean
      fee:
        type: number
      highPrice:
        type: number
      inventory:
        properties:
          available:
            type: integer
          total:
            type: integer
        type: object
      name:
        type: string
      price:
        type: number
      priceCurrency:
        type: string
      priceUnknown:
        type: boolean
      url:
        type: string
  Timeframe:
    properties:
      closes:
        description: Close time for all days mentioned in the dayOfWeek. If close time is less than open, then it is following day.
        format: date-time
        type: string
      dayOfWeek:
        description: ISO day of the week. 1- Monday, 7- Sunday
        items:
          type: integer
        type: array
      open247:
        description: Open around the clock
        type: boolean
      opens:
        description: Open time for all days mentioned in the dayOfWeek
        format: date-time
        type: string
  VirtualLocation:
    description: Virtual Address
    properties:
      domain:
        type: string
      platform:
        type: string
      url:
        type: string
