eBay Category IDs API

The eBay category IDs API is GET /ebay/v1/categories: a name search over eBay's leaf categories, busiest first, or an exact lookup when the query is a numeric id. Its categoryId is what the sold listings search takes as its category filter.

Finds eBay leaf categories by name and returns them busiest first. Use a returned categoryId as the category filter of the sold-listings search.

Every word of query must appear, in any order; matching is case- and accent-insensitive and forgives a trailing plural (cards matches Card). A query made only of digits is an id lookup instead: it returns that exact category, leaf or parent, with a leaf flag.

Category ids differ between marketplaces, so pass the same site you will search with. eBay's category tree has no per-brand categories; to narrow to a brand, combine a generic category id with brand words in the search query.

Cost. 1 credit when at least one category is returned, nothing when none match. At most 200 categories are returned; when total is greater than count, narrow the query.

Request

GEThttps://api.trawl.dev/ebay/v1/categories

Send the API key in the x-api-key header. The samples read it from the TRAWL_API_KEY environment variable.

Parameters

Parameter	Type	Description
`query`required	string	Words to match against category names; every word must appear, in any order. Matching is case- and accent-insensitive. Only the first 12 words are used. A value made only of digits is treated as a category id and returns that exact category.e.g. trading card singles
`site`	EBAY_US \| EBAY_GB	The marketplace whose category tree to search. Category ids are not interchangeable between marketplaces. The value is case-insensitive.default EBAY_US · e.g. EBAY_US

Call it

Fig. 01 — GET /categories

curl "https://api.trawl.dev/ebay/v1/categories?query=trading+card+singles" \
  -H "x-api-key: $TRAWL_API_KEY"

from trawl_api import Trawl

client = Trawl()  # reads TRAWL_API_KEY
found = client.ebay.categories("trading card singles")

import { Trawl } from 'trawl-api'

const client = new Trawl() // reads TRAWL_API_KEY
const found = await client.ebay.categories('trading card singles')

Response

The matching categories, busiest first. categories is empty when nothing matched.

Fields

Field	Type	Description
`site`	EBAY_US \| EBAY_GB	The marketplace whose category tree was searched.
`total`	integer	How many categories matched. Greater than `count` when more than 200 matched.
`count`	integer	The number of entries in `categories`, at most 200.
`categories`	object[]	The matching categories, busiest first. Empty when nothing matched.
`categories[].categoryId`	string	The category id. Use it as the `category` filter of the sold-listings search, on the same `site`.
`categories[].name`	string	The category's name.
`categories[].group`	string	The name of the top-level category this category belongs to, for example `Collectibles`.
`categories[].leaf`	boolean	Whether the category is a leaf. Present only on an id lookup (a `query` made of digits). Only leaf categories can be used as the `category` filter.
`credits_charged`	integer	Credits this response cost. 1 when at least one category is returned, 0 when none matched.

Examples

Fig. 04 — Categories matching "trading card singles"

{
  "site": "EBAY_US",
  "total": 2,
  "count": 2,
  "categories": [
    {
      "categoryId": "261328",
      "name": "Trading Card Singles",
      "group": "Sports Mem, Cards & Fan Shop"
    },
    {
      "categoryId": "183050",
      "name": "Trading Card Singles",
      "group": "Collectibles"
    }
  ],
  "credits_charged": 1
}

{
  "site": "EBAY_US",
  "total": 1,
  "count": 1,
  "categories": [
    {
      "categoryId": "9355",
      "name": "Cell Phones & Smartphones",
      "group": "Cell Phones & Accessories",
      "leaf": true
    }
  ],
  "credits_charged": 1
}

Errors

Every error is a JSON object with one error string and is not charged. The statuses this endpoint answers with:

Status	Meaning
400	A parameter failed validation. The message names the parameter and the rule it broke. Not charged.
403	The `x-api-key` header is missing, or the key is invalid, revoked or belongs to a closed account. Rate-limit headers are not sent on this response.
429	The request was refused and not charged. There are two cases, told apart by the `Retry-After` header. With `Retry-After`, the account's per-second rate was exceeded: wait that many seconds and retry. Without it, the account's monthly credits are spent, or too few remain to cover the most the request could cost: lower `max_pages`, wait for the time in `X-RateLimit-Reset`, or change plan. Retrying without one of those does not help.
500	An internal error. Not charged.
503	The service is temporarily unavailable, or the request took longer than 30 seconds. Not charged. Safe to retry with backoff.