openapi: 3.1.0
info:
description: REST API for concerts, festivals, artists, and venues featuring normalized data from JamBase.
version: 3.1.0
title: JamBase Concert Data Artists API
contact:
email: developer@jambase.com
name: Team JamBase
url: /contact
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: https://www.jambase.com/terms
summary: REST API for live music data from JamBase
servers:
- url: https://api.data.jambase.com/v3
description: JamBase Concert Data API
security:
- BearerAuth: []
tags:
- name: Artists
description: Search Artists
paths:
/artists:
get:
tags:
- Artists
summary: Search Artists
operationId: searchArtists
description: "Search artists by name and genre. \n<!-- theme: info -->\n> #### Requirement\n> Your request must include at least one of the `artistName` or `genreSlug` parameters.\n"
parameters:
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/perPageParam'
- $ref: '#/components/parameters/artistNameParam'
- $ref: '#/components/parameters/genreSlugParam'
- in: query
name: artistHasUpcomingEvents
description: Set to true to only return artists that have at least one upcoming Concert or Festival
schema:
type: boolean
- $ref: '#/components/parameters/dateModifiedFromParam'
- $ref: '#/components/parameters/datePublishedFromParam'
- $ref: '#/components/parameters/expandExternalIdentifiersParam'
- $ref: '#/components/parameters/expandArtistSameAsParam'
responses:
'200':
$ref: '#/components/responses/searchArtistsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
/artists/id/{artistDataSource}:{artistId}:
get:
tags:
- Artists
summary: Get / reverse-lookup an Artist by JamBase or third-party ID
operationId: getSingleArtist
description: 'Retrieve a specific artist by JamBase or third-party ID.
'
parameters:
- in: path
name: artistDataSource
description: the ArtistDataSource of the ID for the artist
required: true
schema:
$ref: '#/components/schemas/enumArtistDataSource'
- in: path
name: artistId
description: the unique ID for the artist
required: true
schema:
type: string
- in: query
name: expandUpcomingEvents
description: Use `true` to include the `event` node with any upcoming events for the artist.
schema:
type: boolean
default: false
- in: query
name: expandUpcomingStreams
description: Use `true` to include the `event` node with any upcoming Streams for the venue.
schema:
type: boolean
default: false
- $ref: '#/components/parameters/excludeEventPerformersParam'
- $ref: '#/components/parameters/expandExternalIdentifiersParam'
- $ref: '#/components/parameters/expandArtistSameAsParam'
- $ref: '#/components/parameters/expandPastEventsParam'
responses:
'200':
$ref: '#/components/responses/getSingleArtistResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedError'
components:
parameters:
expandPastEventsParam:
in: query
name: expandPastEvents
description: 'Use `true` to include past/historical `Concert` and `Festival` objects.
\
When searching events, must be combined with `artistId` or `venueId` parameter.
\
Note: The `expandPastEvents` parameter requires that your apikey has the `expandPastEvents` enhancement turned on. Please contact JamBase to request access to this feature.
'
schema:
type: boolean
default: false
datePublishedFromParam:
in: query
name: datePublishedFrom
description: 'Must have been first published on or after this dateTime in GMT.\
\
If left blank or omitted, will use all first published on dates.
- datePublishedFrom=2022-01-01 00:00:00
Note: Use <a href="https://www.rfc-editor.org/rfc/rfc3339#section-5.6">RFC3339</a> format for parameter values.
'
example: '2022-01-01 00:00:00'
schema:
type: string
format: rfc3339
genreSlugParam:
in: query
name: genreSlug
description: 'Restrict results to a genre.
- genreSlug=bluegrass
Use a pipe (|) to include results from multiple genres.
- genreSlug=bluegrass|blues
'
schema:
$ref: '#/components/schemas/enumGenres'
perPageParam:
in: query
name: perPage
description: Number of events per page of results
required: false
schema:
type: integer
default: 40
minimum: 1
maximum: 100
dateModifiedFromParam:
in: query
name: dateModifiedFrom
description: 'Must have been updated on or after this dateTime in GMT.\
If left blank or omitted, will use all updated on dates
- dateModifiedFrom=2022-10-31 00:00:00
Note: Use <a href="https://www.rfc-editor.org/rfc/rfc3339#section-5.6">RFC3339</a> format for parameter values.
'
example: '2022-10-31 00:00:00'
schema:
type: string
format: rfc3339
pageParam:
in: query
name: page
description: Page number of results to retrieve
required: false
schema:
type: integer
default: 1
artistNameParam:
in: query
name: artistName
description: 'A keyword-based search for artist name(s).
- artistName=Billie%20Eilish
Use a pipe (|) to include multiple artist names.
- artistName=Billie%20Eilish|Lucy%20Dacus
Keywords should be URL Encoded.\
For more precise artist-specific results try using `artistId` or `artist[slug]`.
Please note that `artistName` cannot be used togehter with `artistId` type searches and will be ignored if `artistId` is provided.
'
example: Billie Eilish
schema:
type: string
expandArtistSameAsParam:
in: query
name: expandArtistSameAs
description: 'Use `true` to include `sameAs` (i.e. links) for `Artist` responses.
'
schema:
type: boolean
default: false
excludeEventPerformersParam:
in: query
name: excludeEventPerformers
description: 'Use `true` to suppress the `performer` node in `Concert` and `Festival` objects.
'
schema:
type: boolean
default: false
expandExternalIdentifiersParam:
in: query
name: expandExternalIdentifiers
description: 'Use `true` to include external IDs for `Concert`, `Artist`, and `Venue` objects.
\
Note: The `expandExternalIdentifiers` parameter requires that your apikey has the `expandExternalIdentifiers` enhancement turned on. Please contact JamBase to request access to this feature.
'
schema:
type: boolean
default: false
schemas:
propLatitude:
title: propLatitude
type: number
format: float
minimum: -90
maximum: 90
example: 40.7505
description: The latitude of a location
x-stoplight:
id: 0gf3yu2lypo1r
Request:
title: Request
description: Enclosure for request details.
type: object
properties:
endpoint:
type: string
format: url
description: The base endpoint requested
method:
type: string
description: The request method (e.g. GET, POST)
params:
type: array
items: {}
format: string
description: The parameters for the request
ip:
oneOf:
- type: string
format: ipv4
- type: string
format: ipv6
description: The requesting IP address, IPv4 or IPv6
userAgent:
type: string
format: string
description: The requesting UserAgent
URL:
title: URL
x-stoplight:
id: ac90d6bc4bf17
description: A third-party link.
type: object
properties:
'@type':
type: string
enum:
- URL
identifier:
$ref: '#/components/schemas/enumUrlType'
url:
type: string
format: uri
description: The URL of the external link.
GeoCoordinates:
title: GeoCoordinates
description: The latitude and longitude for a place
type: object
properties:
'@type':
type: string
enum:
- GeoCoordinates
latitude:
$ref: '#/components/schemas/propLatitude'
longitude:
$ref: '#/components/schemas/propLongitude'
propMergedInto:
title: propMergedInto
type: string
example: jambase:5632389
description: 'On a `merged` tombstone (see `deletionStatus`), the `identifier` of the surviving record this one was folded into. Repoint cached references from `identifier` to `mergedInto`.
'
Pagination:
title: Pagination
description: Enclosure for pagination values.
type: object
properties:
page:
type: integer
description: The current page of results.
example: 1
minimum: 0
perPage:
type: integer
description: Number of events per page of results.
example: 10
minimum: 1
totalItems:
type: integer
description: Total results for the request.
example: 50
minimum: 0
totalPages:
type: integer
description: Total pages for the request.
example: 5
minimum: 0
nextPage:
type: string
format: url
description: The absolute URL for the next page of results, if available (e.g. `https://api.data.jambase.com/v3/events?page=2`).
previousPage:
type: string
format: url
description: The absolute URL for the previous page of results, if available (e.g. `https://api.data.jambase.com/v3/events?page=1`).
Offer:
title: Offer
description: Something for sale, typically a concert ticket
type: object
required:
- identifier
- url
- category
- seller
- validFrom
allOf:
- $ref: '#/components/schemas/Thing'
- type: object
properties:
identifier:
type: string
description: A unique identifier of the item
example: jambase:194164
url:
type: string
format: uri
description: URL of the item
category:
type: string
description: The category of the Offer, typically used to identify a primary or secondary ticketing link
examples:
- ticketingLinkPrimary
- ticketingLinkSecondary
priceSpecification:
$ref: '#/components/schemas/PriceSpecification'
seller:
$ref: '#/components/schemas/Organization'
required: true
validFrom:
example: '2022-12-07T12:42:00'
schema:
type: string
format: dateTime
PriceSpecification:
title: PriceSpecification
description: The price or price range for the thing
type: object
required:
- price
- priceCurrency
properties:
'@type':
type: string
enum:
- PriceSpecification
minPrice:
description: The lowest price if the price is a range
type: number
format: decimal
min: 0
example: 15.99
maxPrice:
description: The highest price if the price is a range
type: number
format: decimal
min: 0
example: 35.99
price:
description: The singular price if not a range, same as `minPrice` if a range
type: number
format: decimal
min: 0
example: 35.99
priceCurrency:
type: string
format: iso-4217
description: The currency of the price in ISO 4217 format [[docs](https://en.wikipedia.org/wiki/ISO_4217)]
example: USD
propLongitude:
title: propLongitude
type: number
format: float
minimum: -180
maximum: 180
example: -73.9934
description: The longitude of a location
x-stoplight:
id: udrk05v1mvsv9
MusicVenue:
title: MusicVenue
description: A place to Go See Live Music
type: object
allOf:
- $ref: '#/components/schemas/Thing'
- type: object
properties:
deletionStatus:
$ref: '#/components/schemas/propDeletionStatus'
deletedAt:
$ref: '#/components/schemas/propDeletedAt'
mergedInto:
$ref: '#/components/schemas/propMergedInto'
maximumAttendeeCapacity:
type: number
format: int32
example: 20789
description: The total number of individuals that may attend an event or venue.
address:
$ref: '#/components/schemas/PostalAddress'
geo:
$ref: '#/components/schemas/GeoCoordinates'
events:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Concert'
- $ref: '#/components/schemas/Festival'
x-isPermanentlyClosed:
type: boolean
default: false
description: If the venue is permanently closed.
x-numUpcomingEvents:
type: number
format: int32
example: 12
description: The number of upcoming events at this venue.
x-externalIdentifiers:
type: array
items:
- $ref: '#/components/schemas/ExternalIdentifier'
Event:
title: Event
description: 'A generic event.Please note that `startDate`,`endDate`,`previousStartDate`, and `doorTime` are all returned based on the venue''s local time but without an offset. You can find the timezone at `event > location > address > x-timezone` if you need to do any conversions.
'
type: object
allOf:
- $ref: '#/components/schemas/Thing'
properties:
sameAs:
description: Only available for `Festival` type events, not `Concert`
- type: object
properties:
eventStatus:
$ref: '#/components/schemas/enumEventStatus'
startDate:
type: string
format: iso-8601
description: 'The start date and time of the item using ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that `startDate` is returned based on the venue''s local time but without an offset. You can find the timezone at `event > location > address > x-timezone` if you need to do any conversions.
'
endDate:
type: string
format: iso-8601
description: 'The end date of the item using ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that `endDate` is returned based on the venue''s local time but without an offset. You can find the timezone at `event > location > address > x-timezone` if you need to do any conversions.
'
previousStartDate:
type: string
format: iso-8601
description: 'For rescheduled events, the previously scheduled start date using ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that `previousStartDate` is returned based on the venue''s local time but without an offset. You can find the timezone at `event > location > address > x-timezone` if you need to do any conversions.
'
doorTime:
type: string
format: iso-8601
description: 'The time admission will commence in local time using ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that `doorTime` is returned based on the venue''s local time but without an offset. You can find the timezone at `event > location > address > x-timezone` if you need to do any conversions.
'
location:
$ref: '#/components/schemas/MusicVenue'
offers:
type: array
items:
$ref: '#/components/schemas/Offer'
performer:
type: array
items:
allOf:
- $ref: '#/components/schemas/MusicGroup'
- type: object
properties:
x-performanceDate:
type: string
format: iso-8601
description: 'The date of the performance using ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
'
x-performanceRank:
type: number
format: int32
require: true
description: The "rank" for this performance whithin the event
x-isHeadliner:
type: boolean
default: false
require: true
description: If this performer is a headliner
x-dateIsConfirmed:
type: boolean
default: false
description: 'Required for Festivals.
If a Festival performance date is confirmed or not.\
If not, it will appear on the first day of the Festival.
'
eventAttendanceMode:
$ref: '#/components/schemas/enumAttendanceMode'
isAccessibleForFree:
type: boolean
default: false
x-promoImage:
type: string
format: uri
description: A secondary promotional image for the event (e.g. admat)
State:
title: State
description: 'A State, Region, or Province.
\
Note 1: Available for United States, Canada, and Australia only.
\
Note 2: The `country` and `x-numUpcomingEvents` nodes are only provided in the Geography lookup endpoints, not as part of `addressRegion` within a Concert, Festival, or Stream.
'
type: object
x-stoplight:
id: rbp08k99t5o7m
properties:
'@type':
type: string
enum:
- State
identifier:
$ref: '#/components/schemas/enumState'
name:
type: string
example: Arizona
description: The name of the State
alternateName:
type: string
example: AZ
description: The indentifier without the Country code prefix
country:
$ref: '#/components/schemas/Country'
description: 'The country in which the state belongs.
\
Note: this is only provided in the Geography lookup endpoints, not as part of a location''s `addressCountry` within a Concert, Festival, or Stream.
'
x-numUpcomingEvents:
type: number
format: int32
example: 12
description: 'The number of upcoming events in this State.
\
Note: this is only provided in the Geography lookup endpoints, not as part of a location within a Concert, Festival, or Stream.
'
Country:
title: Country
description: A Country.
type: object
properties:
'@type':
type: string
enum:
- Country
identifier:
$ref: '#/components/schemas/enumCountryIso2'
name:
type: string
example: United States
description: The name of the Country Area
alternateName:
$ref: '#/components/schemas/enumCountryIso3'
x-numUpcomingEvents:
type: number
format: int32
example: 12
description: 'The number of upcoming events in this Country.
\
Note: this is only provided in the Geography lookup endpoints, not as part of a location within a Concert, Festival, or Stream.
'
Organization:
title: Organization
description: 'An organization or business.\
Typically a ticket vendor or data source in this API.\
The `identifier` or "slug" can also be used as `ticket[vendor][id]` in `/events` and `/livestreams` search endpoints.
'
type: object
required:
- name
- identifier
- disambiguatingDescription
- datePublished
- dateModified
allOf:
- type: object
properties:
'@type':
type: string
enum:
- Organization
identifier:
type: string
description: A unique identifier of the item
example: ticketmaster
disambiguatingDescription:
type: string
examples:
- eventTicketVendorPrimary
- eventTicketVendorSecondary
- streamTicketVendorPrimary
- streamDataSource
- eventDataSource
- artistDataSource
- venueDataSource
- $ref: '#/components/schemas/Thing'
enumCountryIso2:
type: string
format: iso-3166-alpha-2
example: US
description: 'The Country code in ISO 3166-1 alpha-2 format [[docs](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)].
'
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AR
- AS
- AT
- AU
- AW
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BR
- BS
- BT
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- US
- UY
- UZ
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- XD
- XG
- XK
- XP
- XR
- XS
- XW
- YE
- YT
- ZA
- ZM
- ZW
x-stoplight:
id: 1ef0ob0u4hu6w
x-tags:
- Enums
propDeletedAt:
title: propDeletedAt
type: string
format: iso-8601
example: '2026-04-12T18:01:00Z'
description: 'The moment the record left the catalog, in ISO 8601. Present only on tombstone rows (see `deletionStatus`). Equals the row''s `dateModified` so the same `dateModifiedFrom` watermark that catches updates also catches the removal.
'
enumVenueDataSource:
type: string
description: Data source slugs to use for Venue IDs
enum:
- axs
- dice
- etix
- eventbrite
- eventim-de
- jambase
- seated
- seatgeek
- suitehop
- ticketmaster
- viagogo
x-stoplight:
id: vg16q2jczs7fg
x-tags:
- Enums
ExternalIdentifier:
title: ExternalIdentifier
description: A third-party non-JamBase ID for an artist, venue, or event.
type: object
properties:
'@type':
type: string
enum:
- ExternalIdentifier
source:
oneOf:
- $ref: '#/components/schemas/enumEventDataSource'
- $ref: '#/components/schemas/enumArtistDataSource'
- $ref: '#/components/schemas/enumVenueDataSource'
identifier:
type: string
description: The unique identifier of the item from the third-party source.
examples:
- '@type': ExternalIdentifier
source: ticketmaster
identifier: e3asdf3ad
- '@type': ExternalIdentifier
source: axs
identifier: '123423'
enumAttendanceMode:
type: string
default: offline
description: Indicates whether it occurs online, offline, or a mix.
enum:
- mixed
- offline
- online
x-tags:
- Enums
ErrorsList:
description: A list of errors
x-stoplight:
id: 1253ab38a345c
type: array
items:
type: object
properties:
errorCode:
type: string
enum:
- no_lookup_results
- lookup_error
- parameter_missing
- parameter_invalid
- identifier_missing
- identifier_invalid
- parameter_out_of_range
- general_error
errorMessage:
type: string
example: The identifier `jambase:87121` is invalid.
enumGenres:
type: string
description: Music genres
summary: Multiple genres
enum:
- bluegrass
- blues
- christian
- classical
- country-music
- edm
- folk
- hip-hop-rap
- indie
- jamband
- jazz
- kpop
- latin
- metal
- pop
- punk
- reggae
- rhythm-and-blues-soul
- rock
- tribute
x-tags:
- Enums
Thing:
title: Thing
description: A generic thing
type: object
properties:
name:
type: string
description: The name of the item
identifier:
type: string
example: jambase:194164
description: A unique identifier of the item
url:
type: string
format: uri
description: URL of the item
image:
type: string
format: uri
description: 'An image of the item.\
\
Please note that ''image'' may not be provided for all Schemas that include `Thing` (e.g. `Organization`)
'
sameAs:
type: array
items:
$ref: '#/components/schemas/URL'
description: URL of a reference Web page that unambiguously indicates the item's identity
datePublished:
type: string
format: iso-8601
example: '2022-12-14T15:35:48Z'
description: 'The date the Event first appeared in ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that ''datePublished'' may not be provided for all Schemas that include `Thing` (e.g. `Organization`)
'
dateModified:
type: string
format: iso-8601
example: '2022-12-14T03:41:20Z'
description: 'The date the Event was last updated in ISO 8601 date format [[docs](https://en.wikipedia.org/wiki/ISO_8601)]
\
Please note that ''dateModified'' may not be provided for all Schemas that include `Thing` (e.g. `Organization`).
\
Indexing timestamps for Concert / Festival / Stream / MusicGroup / MusicVenue live on `datePublished` and `dateModified`. The sibling `x-createdOnDate` and `x-updatedOnDate` fields are scoped to data-source / `Organization` responses (e.g. ticket vendors, performance-rights organizations) and are not present on Event-derived schemas.
'
propDeletionStatus:
title: propDeletionStatus
type: string
enum:
- deleted
- trashed
- merged
example: deleted
description: 'Present ONLY on tombstone rows returned by delta polls of the core feeds (i.e. requests that include `dateModifiedFrom`). Marks a record that has left the catalog so a long-lived mirror can drop or redirect it:
- `deleted` — permanently removed.
- `trashed` — soft-deleted (events only; recoverable upstream). Treat the same as `deleted` in your cache.
- `merged` — folded into another record; follow `mergedInto`.
\
A tombstone row carries only `@type`, `identifier`, `deletionStatus`, `deletedAt`, `dateModified`, and (when `merged`) `mergedInto` — no other fields. Tombstones count toward `perPage` and `pagination.totalItems` and are appended after the live rows in the merged result sequence. Retention: `deleted` / `trashed` tombstones are emitted for 90 days after `deletedAt`; `merged` tombstones never expire. Queries WITHOUT `dateModifiedFrom` never return tombstones.
'
enumUrlType:
type: string
x-stoplight:
id: cf4040b56ddd2
description: The type of the external URL
enum:
- officialSite
- facebook
- twitter
- instagram
- youtube
- musicbrainz
- spotify
- androidApp
- iosApp
x-tags:
- Enums
MusicGroup:
title: MusicGroup
description: A band or musician
type: object
allOf:
- $ref: '#/components/schemas/Thing'
- type: object
properties:
'@type':
type: string
enum:
- MusicGroup
deletionStatus:
$ref: '#/components/schemas/propDeletionStatus'
deletedAt:
$ref: '#/components/schemas/propDeletedAt'
mergedInto:
$ref: '#/components/schemas/propMergedInto'
member:
type: array
description: For bands, an array of the band's members
items:
type: object
properties:
type:
type: string
enum:
- MusicGroup
name:
type: string
description: The name of the item
identifier:
type: string
example: jambase:12345
description: A unique identifier of the item
image:
type: string
format: uri
description: An image of the item
url:
type: string
format: uri
description: URL of
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/jambase/refs/heads/main/openapi/jambase-artists-api-openapi.yml