Please enable JS in your browser for better work of developer.ticketmaster.com

Top Picks API

The Top Picks API provides seat recommendations based on current availability, sampling across various areas of a venue and available price points. Results are near real-time but for certain high velocity events picks may expire (sell out) quickly.

Overview

Authentication

Clients will be provided an API key from Ticketmaster which should be added to every resource endpoint call.

Example: https://app.ticketmaster.com/top-picks/v1/events/3F004EC9D1EBBC76?apikey=3QIvq55bS608ai6r8moig1WdW57bONry

Countries supported:

North America.

Host and API endpoint information

Environment Endpoint
Pre-prod https://app.ticketmaster.com/top-picks-preprod/v1
Production https://app.ticketmaster.com/top-picks/v1

All connections must be made over SSL using https.

Terms and Conditions

By using the Ticketmaster Developer Portal, you understand and agree to our Terms of Use.

Contact

Please contact us if you have any questions.

Service Availability

The Ticketmaster back-end reservation systems are distributed globally and events are processed on their local systems. These systems go into a nightly maintenance mode at 2AM local time. This means a show playing at Madison Square Garden will not be transactable between 2AM-4AM Eastern Time. Use the timezone value from the event details response to note when these events may be unavailable for transactions.

Rate Limit

All API keys are issued with a default quota of 1200 API calls per min.

Rate Limit Info in Response Header

You can see how much of your quota has been used by checking the following response headers:

  • Ratelimit-Quota-Available: What’s the rate limit available to you. This will be 1200 minus all the requests you’ve done.
  • Ratelimit-Quota-Allowed: How many requests are available to you. The default is 1200/min.
  • Ratelimit-Expiry: Returns the UTC time in milliseconds which determines when the quota expires and new quota interval starts.

API Response When Quota is Reached

When you do go over your quota, you will get an HTTP status code 429 indicating you’ve made too many requests. The following is the API response you will receive:

{
  "fault": {
    "faultstring": "Rate limit quota violation. Quota limit  exceeded. Identifier : {apikey}",
    "detail": {
      "errorcode": "policies.ratelimit.QuotaViolation"
    }
  }
}

Top Picks Details [GET]

Retrieve reservable seat information based on specific criteria.

/top-picks/v1/events/{event_id}?apikey={apikey}

Universal Ids Support

The TopPicks service also supports queries using universal ids via the path

/top-picks/v1/events/id/{universalEventId}?apikey={apikey}

URL Parameters

Parameter Description Type Example Required
event_id The 16-digit alphanumeric event ID. string “0B004ED9FC825ACB” Yes

Query Parameters

Parameter Description Type Example Required
apikey Your API Key string GkB8Z037ZfqbLCNtZViAgrEegbsrZ6Ne Yes
quantity Quantity of tickets number 2 No (default=2)
ticketTypeId Ticket type ID string 000000000001 No
priceLevels Comma-separated price Levels to search numbers 0,1 No
areas Comma-separated area IDs to search numbers 10,11 No
sections Comma-separated section names string GA,103,201 No
prices Price range numbers 50,150 No
page Page number numbers 1 No
limit Elements per page numbers 100 No (default=100) The backend service is restricted to return only 100 elements.
selection Comma-separated type of tickets string Any, Standard, Platinum, Resale( Platinum and Resale is only available for select apikeys specifically configured for that.) No (default=Standard)
sort Sort order string - listprice - sorts by face value in ascending order
- quality - sorts by quality in descending order; does not apply to 3rd party resale.
- section - sorts by section, then by row, and then by list price; applies to 3rd party resale only.		 No (default=listprice)

Response structure:

  • page (object) - Page information.
    • number (number) - current page number counted from 1.
    • size (number) - size of current page (max=30 per page).
    • totalElements (number) - total number of elements available.
    • totalPages (number) - total number of pages available.
  • picks (array) - Picks.
    • {array item object} - pick.
      • type (string) - “general-seating”, or “seats”
      • quality (number) - A quality score representing a combination of price and location to stage.
      • area (object) - An area information
        • id (string) - Area id
        • name (string) - Area name
        • description (string) - Area description
      • descriptions (array) - A list of descriptions for this pick
      • section (string) - The section name in the venue
      • selection (string) - “standard”, or “resale”.
      • row (string) - The row in the section, if applicable (not available during onsale).
      • snapshotImageUrl - An image url of this pick in the venue. If the venue or event doesn’t support detailed images, this field will be null.
      • offers (array) - Offers.
        • {array item object} - offer.
          • offer id (string) - The offer id corresponding to one in _embedded.offer[].
      • seats (array) - Seats (not available during onsale).
        • {array item object} - seat.
          • seat id (string) - seat names.
  • _embedded (object) - container for events.
    • offer (array) - Offers matching those found in picks[] items.
      • {array item object} - offer.
        • offerId (string) - The offer id.
        • name (string) - Name of the offer.
        • ticketTypeId (string) - Ticket type id required for reserves.
        • priceLevelId (string) - Price level id (optional for reserves).
        • description (string) - Description of the offer.
        • currency (string) - ISO 4217 currency code.
        • faceValue (number) - Face value of one ticket.
        • totalPrice (number) - Total price including charges (may not include order processing fees).
        • charges (array) - Charges.
          • {array item object} - charge.
            • reason (string) - Name of charge.
            • type (string) - Type of charge.
            • amount (number) - Amount of charge
            • fee_type (string) - Type of fee (e.g. PER TICKET)
        • limit(object) - ticket limits info
          • min (number) - Min no of tickets
          • max (number) - Max no of tickets
        • promotions(array) - promotions.
  • eventDetails (object)- Event details
    • id (string) - Id of the event
    • granularPricing (boolean) - True/False based on if the event is granular pricing
    • venueMapUrl (string) - Url for venue map
    • venueMapWithLabelsUrl (string) - Url for venue map with labels
    • safeTixEnabled (boolean) - True/False based on if the event is safetix enabled/enforced
    • allInclusivePricing (boolean) - True/False based on if the event is using all-in pricing
    • transfer (object) - Transfer Eligibility
      • eligible (boolean) - True/False based on if tickets to the event are transferable
      • explanation (string) - Explanation of transfer eligibility status

Request Response

https://app.ticketmaster.com/top-picks/v1/events/2000527EE48A9334?apikey=GkB8Z037ZfqbLCNtZViAgrEegbsrZ6Ne&areas=10,11&prices=70,150&quantity=4&ticketTypeId=000000000001&sections=103
Status 200
{
  "page": {
    "number": 1,
    "size": 28,
    "totalElements": 28,
    "totalPages": 1
  },
  "picks": [
    {
      "type": "general-seating",
      "quality": 1.0,
      "section": "GAPIT1",
      "selection": "standard",
      "snapshotImageUrl": "https://app.ticketmaster.com/maps/geometry/3/event/2000527EE48A9334/image?systemId=HOST&segmentIds=s_183&app=TOPPICKS",
      "area": {
        "id": "14",
        "name": "GA",
        "description": "GENERAL ADMISSION STANDING"
      },
      "offers": [
        "GJ6DIQJTIMYDAMCBPQZQ"
      ]
    },
    {
      "type": "general-seating",
      "quality": 1.0,
      "section": "GAPIT1",
      "selection": "standard",
      "snapshotImageUrl": "https://app.ticketmaster.com/maps/geometry/3/event/2000527EE48A9334/image?systemId=HOST&segmentIds=s_183&app=TOPPICKS",
      "area": {
        "id": "14",
        "name": "GA",
        "description": "GENERAL ADMISSION STANDING"
      },
      "offers": [
        "GJ6DC7BT"
      ]
    },
    {
      "type": "seats",
      "quality": 0.996241,
      "section": "4",
      "selection": "standard",
      "row": "1",
      "snapshotImageUrl": "https://app.ticketmaster.com/maps/geometry/3/event/2000527EE48A9334/image?systemId=HOST&sectionNames=4&placeId=GQ5DCORR&app=TOPPICKS",
      "area": {
        "id": "13",
        "name": "FLOOR",
        "description": "Floor Seating"
      },
      "offers": [
        "GJ6DC7BT"
      ],
      "seats": [
        "1",
        "2"
      ],
      "coordinates": [
        {
          "x": 451.76,
          "y": 408.52
        },
        {
          "x": 451.76,
          "y": 409.72
        }
      ]
    }
  ],
  "_embedded": {
    "offer": [
      {
        "offerId": "GJ6DIQJTIMYDAMCBPQZQ",
        "name": "$20 All In Tickets",
        "ticketTypeId": "00004A3C000A",
        "priceLevelId": "3",
        "description": "$20 All In Tickets",
        "currency": "USD",
        "faceValue": 25.0,
        "totalPrice": 25.0,
        "charges": [    
            {
                "reason": "facility",
                "type": "fee",
                "amount": 8
              },
              {
                "reason": "order_processing",
                "type": "fee",
                "amount": 0
              },
              {
                "reason": "service",
                "type": "fee",
                "amount": 15.8
              },
               {
                  "reason": "service",
                  "type": "fee",
                  "amount": 15.8
               },
               {
                  "reason": "service",
                  "type": "tax",
                  "amount": 2
                },
                {
                  "reason": "face_value_tax",
                  "type": "tax",
                  "amount": 3
                },
                {
                "reason": "service_tax_2",
                "type": "tax",
                "amount": 0.33
                }
        ],
        "limit": {
          "min": 1,
          "max": 50
        },
        "promotions": [         
        ]
      },
      {
        "offerId": "GJ6DC7BT",
        "name": "Standard Ticket",
        "ticketTypeId": "000000000001",
        "priceLevelId": "3",
        "description": "Standard Ticket",
        "currency": "USD",
        "faceValue": 285.0,
        "totalPrice": 298.75,
        "charges":[
          {
              "reason": "facility",
              "type": "fee",
              "amount": 8
            },
            {
              "reason": "order_processing",
              "type": "fee",
              "amount": 0
            },
            {
              "reason": "service",
              "type": "fee",
              "amount": 15.8
            },
             {
                "reason": "service",
                "type": "fee",
                "amount": 15.8
             },
             {
                "reason": "service",
                "type": "tax",
                "amount": 2
              },
              {
                "reason": "face_value_tax",
                "type": "tax",
                "amount": 3
              },
              {
              "reason": "service_tax_2",
              "type": "tax",
              "amount": 0.33
              }
        ],
        "limit": {
          "min": 1,
          "max": 50
        },
        "promotions": [  
        ]
      }
    ]
  },
  "eventDetails": {
    "id": "2000527EE48A9334",
    "granularPricing": false,
    "venueMapUrl": "https://app.ticketmaster.com/maps/geometry/3/event/2000527EE48A9334/image?systemId=HOST&app=TOPPICKS&pw=0",
    "venueMapWithLabelsUrl": "https://app.ticketmaster.com/maps/geometry/3/event/2000527EE48A9334/image?systemId=HOST&app=TOPPICKS&pw=0&showLabels=true",
    "safeTixEnabled": false,
    "allInclusivePricing": false,
    "transfer": {
      "eligible": true,
      "explanation": "Tickets for this event will be fulfilled by the original ticket provider for this event. Ticket transfer, if allowed, is only available through the original ticket provider."
    }
  }
}

Response for All-in Pricing Enabled Event

This is how the Top Picks API response will appear if all-in pricing is enabled. More details on the all-in pricing changes in Top Picks here.

Request Response

https://app.ticketmaster.com/top-picks/v1/events/00005EAFA1A64023?apikey=GkB8Z037ZfqbLCNtZViAgrEegbsrZ6Ne&ticketTypeId=000000000001&quantity=4&sections=BALCL
Status 200
{
  "page": {
    "number": 1,
    "size": 2,
    "totalElements": 2,
    "totalPages": 1
  },
  "picks": [
    {
      "type": "seats",
      "quality": 0.272727,
      "section": "BALCL",
      "selection": "standard",
      "row": "BB",
      "snapshotImageUrl": "https://app.ticketmaster.com/maps/geometry/3/event/00005EAFA1A64023/image?systemId=HOST&sectionNames=BALCL&placeId=IJAUYQ2MHJBEEORT&app=TOPPICKS",
      "descriptions": [
        "Left Section"
      ],
      "area": {
        "id": "6",
        "name": "BALC",
        "description": "Balcony Box Seating"
      },
      "offers": [
        "GJ6DC7BVGQ"
      ],
      "seats": [
        "3",
        "5",
        "7",
        "9"
      ],
      "coordinates": [
        {
          "x": 819.96,
          "y": 510.59
        },
        {
          "x": 816.97,
          "y": 523.45
        },
        {
          "x": 813.98,
          "y": 536.31
        },
        {
          "x": 810.99,
          "y": 549.16
        }
      ]
    },
    {
      "type": "seats",
      "quality": 0.136364,
      "section": "BALCL",
      "selection": "standard",
      "row": "A",
      "snapshotImageUrl": "https://app.ticketmaster.com/maps/geometry/3/event/00005EAFA1A64023/image?systemId=HOST&sectionNames=BALCL&placeId=IJAUYQ2MHJATUOI&app=TOPPICKS",
      "descriptions": [
        "Left Section"
      ],
      "area": {
        "id": "6",
        "name": "BALC",
        "description": "Balcony Box Seating"
      },
      "offers": [
        "GJ6DC7BVGQ"
      ],
      "seats": [
        "9",
        "11",
        "13",
        "15"
      ],
      "coordinates": [
        {
          "x": 771.29,
          "y": 552.89
        },
        {
          "x": 768.3,
          "y": 565.75
        },
        {
          "x": 765.31,
          "y": 578.6
        },
        {
          "x": 762.32,
          "y": 591.46
        }
      ]
    }
  ],
  "_embedded": {
    "offer": [
      {
        "offerId": "GJ6DC7BVGQ",
        "name": "Standard Admission",
        "ticketTypeId": "000000000001",
        "priceLevelId": "54",
        "description": "Standard Admission",
        "currency": "USD",
        "faceValue": 40.0,
        "totalPrice": 53.35,
        "charges": [
          {
            "reason": "service",
            "type": "fee",
            "amount": 13.35,
            "fee_type": "PER TICKET"
          },
          {
            "reason": "order_processing",
            "type": "fee",
            "amount": 3.1,
            "fee_type": "PER ORDER"
          }
        ],
        "limit": {
          "min": 1,
          "max": 8
        },
        "promotions": [],
        "protected": false
      }
    ]
  },
  "eventDetails": {
    "id": "00005EAFA1A64023",
    "granularPricing": false,
    "venueMapUrl": "https://app.ticketmaster.com/maps/geometry/3/event/00005EAFA1A64023/image?systemId=HOST&app=TOPPICKS&pw=0",
    "venueMapWithLabelsUrl": "https://app.ticketmaster.com/maps/geometry/3/event/00005EAFA1A64023/image?systemId=HOST&app=TOPPICKS&pw=0&showLabels=true",
    "safeTixEnabled": true,
    "allInclusivePricing": true,
    "transfer": {
      "eligible": true,
      "explanation": "Tickets for this event will be fulfilled by the original ticket provider for this event. Ticket transfer, if allowed, is only available through the original ticket provider."
    }
  }
}

Snapshot Image [GET]

A visual-representation of the approximate location of seats in the venue. Each result from the Top Picks API contains a snapshotImageUrl of a .png image.

Query Parameters

All query parameters in snapshotImageUrl must be maintained and un-altered. Clients may add the following:

Parameter Description Type Example Required
w The width, in pixels, of the image. (min: 102, max: 1024) number 300 No
pw The width, in pixels, of the dropped pin in the image. number 30 No
apikey Your API Key string “GkB8Z037ZfqbLCNtZViAgrEegbsrZ6Ne” Yes

Response

Status Code Note
200 Image Rendered
204 Image not available. Event may not be configured with interactive seat map data.

Sample response for status=200

pick image

Example use of Top Picks data

pick image

Pod Seating

Pod Seating is a seating arrangement that allows an event to operate at reduced capacity so family and friends can maintain a socially safe distance from other attendees. Pod Seating enables venues to sell seats together as a group or ‘pod’ (e.g., pod of 4 seats), and each pod is spaced apart from other pods based on local health and safety guidelines. To maintain pod integrity, ticket buyers are required to purchase the entire pod and may not split the pod, ensuring that people who chose to attend an event together will not sit next to other people who are unknown to them. A variety of venues have adopted Pod Seating, including concerts, comedy shows and sports leagues.

Top Picks API Response

The Top Picks API will return each Pod Seating offer under “tickettypes” if an event has implemented Pod Seating. Each offer will contain a name, ticket type ID and sellable ticket quantities (displayed as “sellableQuantities”), which represents the number of tickets that fans can purchase in a single transaction. Fans may only buy tickets in a quantity shown under sellableQuantities. If a fan attempts to purchase tickets in any other amount, the Reserve response will return return a 400 error with the message “Inventory authorization failure due to limit violation”. The Top Picks API will only return “tickettypes” for events using Pod Seating; otherwise, the field will be empty.

Request Response

https://app.ticketmaster.com/top-picks/v1/events/<eventId>?apikey=<apikey>
{
   "page":{
      "number":1,
      "size":7,
      "totalElements":7,
      "totalPages":1
   },
   "picks":[
      {
         "type":"seats",
         "quality":0.066667,
         "section":"BOXA",
         "selection":"standard",
         "row":"A",
         "snapshotImageUrl":"https://app.ticketmaster.com/maps/geometry/3/event/0D00585BD380F769/image?systemId=HOST&sectionNames=BOXA&placeId=IJHVQQJ2IE5DM&app=TOPPICKS",
         "descriptions":[
            "RIGHT"
         ],
         "area":{
            "id":"0",
            "name":"BOX",
            "description":"BOX SEATING"
         },
         "offers":[
            "GJ6DKMRYGAYDAMBQGAYDC7BR"
         ],
         "seats":[
            "6",
            "8"
         ],
         "coordinates":[
            {
               "x":231.3,
               "y":542.34
            },
            {
               "x":223.08,
               "y":504.36
            }
         ]
      },
      {
         "type":"seats",
         "quality":0.030303,
         "section":"ORCHWC",
         "selection":"standard",
         "row":"A",
         "snapshotImageUrl":"https://app.ticketmaster.com/maps/geometry/3/event/0D00585BD380F769/image?systemId=HOST&sectionNames=ORCHWC&placeId=J5JEGSCXIM5ECORRGEZA&app=TOPPICKS",
         "area":{
            "id":"3",
            "name":"ORCH",
            "description":"ORCHESTRA SEATING"
         },
         "offers":[
            "GJ6DKMRYGAYDAMBQGAYDC7BR"
         ],
         "seats":[
            "112",
            "113"
         ],
         "coordinates":[
            {
               "x":590.96,
               "y":595.11
            },
            {
               "x":608.95,
               "y":601.37
            }
         ]
      },
      {
         "type":"seats",
         "quality":0.269697,
         "section":"ORCH",
         "selection":"standard",
         "row":"N",
         "snapshotImageUrl":"https://app.ticketmaster.com/maps/geometry/3/event/0D00585BD380F769/image?systemId=HOST&sectionNames=ORCH&placeId=J5JEGSB2JY5DCMBS&app=TOPPICKS",
         "area":{
            "id":"3",
            "name":"ORCH",
            "description":"ORCHESTRA SEATING"
         },
         "offers":[
            "GJ6DGMJYGAYDAMBQGAYDC7BR"
         ],
         "seats":[
            "102",
            "103"
         ],
         "coordinates":[
            {
               "x":333.23,
               "y":161.84
            },
            {
               "x":351.48,
               "y":158.43
            }
         ]
      }
   ],
   "_embedded":{
      "offer":[
         {
            "offerId":"GJ6DKMRYGAYDAMBQGAYDC7BR",
            "name":"ADA Pod Seating - Group of 2",
            "ticketTypeId":"052800000001",
            "priceLevelId":"1",
            "description":"ADA Pod Seating - Group of 2",
            "currency":"USD",
            "faceValue":45,
            "totalPrice":55.46,
            "charges":[
               {
                  "reason":"facility",
                  "type":"fee",
                  "amount":2,
                  "fee_type":"PER TICKET"
               },
               {
                  "reason":"service",
                  "type":"fee",
                  "amount":8.46,
                  "fee_type":"PER TICKET"
               },
               {
               "reason": "order_processing",
               "type": "fee",
               "amount": 5.5,
               "fee_type": "PER ORDER"
               },
               {
               "reason": "service_tax",
               "type": "tax",
               "amount": 2.08,
               "fee_type": "PER TICKET"
               },
               {
               "reason": "face_value_tax",
               "type": "tax",
               "amount": 2.08,
               "fee_type": "PER TICKET"
               },
               {
               "reason": "service_tax_2",
               "type": "tax",
               "amount": 0.33,
               "fee_type": "PER TICKET"
               }
            ],
            "limit":{
               "min":2,
               "max":2
            },
            "promotions":[
            ]
         },
         {
            "offerId":"GJ6DGMJYGAYDAMBQGAYDC7BR",
            "name":"Standard Ticket - Group of 2",
            "ticketTypeId":"031800000001",
            "priceLevelId":"1",
            "description":"Standard Ticket - Group of 2",
            "currency":"USD",
            "faceValue":45,
            "totalPrice":55.46,
            "charges":[
               {
                  "reason":"facility",
                  "type":"fee",
                  "amount":2,
                  "fee_type":"PER TICKET"
               },
               {
                  "reason":"service",
                  "type":"fee",
                  "amount":8.46,
                  "fee_type":"PER TICKET"
               },
               ,
              {
                  "reason": "order_processing",
                  "type": "fee",
                  "amount": 5.5,
                  "fee_type": "PER ORDER"
              },
              {
                  "reason": "service_tax",
                  "type": "tax",
                  "amount": 2.08,
                  "fee_type": "PER TICKET"
              },
              {
                  "reason": "face_value_tax",
                  "type": "tax",
                  "amount": 2.08,
                  "fee_type": "PER TICKET"
              },
              {
                 "reason": "service_tax_2",
                 "type": "tax",
                 "amount": 0.33,
                 "fee_type": "PER TICKET"
              }
            ],
            "limit":{
               "min":2,
               "max":2
            },
            "promotions":[
            ]
         }
      ]
   },
   "eventDetails":{
      "id":"0D00585BD380F769",
      "granularPricing":false,
      "venueMapUrl":"https://app.ticketmaster.com/maps/geometry/3/event/0D00585BD380F769/image?systemId=HOST&app=TOPPICKS&pw=0",
      "venueMapWithLabelsUrl":"https://app.ticketmaster.com/maps/geometry/3/event/0D00585BD380F769/image?systemId=HOST&app=TOPPICKS&pw=0&showLabels=true",
      "safeTixEnabled":false
   },
   "tickettypes":[
      {
         "ticketTypeId":"021000000001",
         "sellableQuantities":[
            1
         ],
         "name":"Standard Ticket - Group of 1"
      },
      {
         "ticketTypeId":"031800000001",
         "sellableQuantities":[
            2
         ],
         "name":"Standard Ticket - Group of 2"
      },
      {
         "ticketTypeId":"042000000001",
         "sellableQuantities":[
            4
         ],
         "name":"Standard Ticket - Group of 4"
      },
      {
         "ticketTypeId":"052800000001",
         "sellableQuantities":[
            2
         ],
         "name":"ADA Pod Seating - Group of 2"
      }
   ]
}