Skip to main content

Searching Categories

The categories query allows you to search for podcast categories directly through the GraphQL API. This makes it easy to discover available categories, explore them, and use category slugs to filter podcasts.

If you haven't already, you will need to get your authorization token which you can get by following our "Your First Podchaser Query" guide.

You can search for categories using the categories query. The searchTerm parameter will match against both the category title (text) and slug fields. The query returns a paginated list with data and paginatorInfo fields.

POST https://api.podchaser.com/graphql
query {
    categories(searchTerm: "technology", first: 25) {
        paginatorInfo {
            count
            currentPage
            hasMorePages
            lastPage
            perPage
            total
        }
        data {
            title
            slug
            podcastCount
        }
    }
}

This query will return categories that match "technology" in either their title or slug:

{
    "data": {
        "categories": {
            "paginatorInfo": {
                "count": 2,
                "currentPage": 0,
                "hasMorePages": false,
                "lastPage": 0,
                "perPage": 25,
                "total": 2
            },
            "data": [
                {
                    "title": "Technology",
                    "slug": "technology",
                    "podcastCount": 1234
                },
                {
                    "title": "Tech News",
                    "slug": "tech-news",
                    "podcastCount": 567
                }
            ]
        }
    }
}

Searching Without a Term​

You can also query all categories without providing a search term:

query {
    categories(first: 25) {
        paginatorInfo {
            total
            perPage
            currentPage
        }
        data {
            title
            slug
            podcastCount
        }
    }
}

Sorting Categories​

You can sort category results by different criteria:

Sort by Podcast Count (default)​

Sort categories by the number of podcasts they contain:

query {
    categories(sort: { sortBy: PODCAST_COUNT, direction: DESCENDING }, first: 25) {
        data {
            title
            slug
            podcastCount
        }
    }
}

Sort Alphabetically​

Sort categories alphabetically by title:

query {
    categories(sort: { sortBy: ALPHABETICAL, direction: ASCENDING }, first: 25) {
        data {
            title
            slug
            podcastCount
        }
    }
}

Sort by Relevance​

When you provide a search term, you can sort by relevance:

query {
    categories(
        searchTerm: "business",
        sort: { sortBy: RELEVANCE, direction: DESCENDING },
        first: 25
    ) {
        data {
            title
            slug
            podcastCount
        }
    }
}

Filtering Categories​

You can filter categories by chart platform and podcast count:

Filter by Chart Platform​

Filter categories to only show those available on specific chart platforms:

query {
    categories(filters: { inCharts: [APPLE_PODCASTS] }, first: 25) {
        data {
            title
            slug
            podcastCount
            chartPlatforms
        }
    }
}

This will return only categories that are available on Apple Podcasts charts. You can also use [SPOTIFY] or [SPOTIFY,APPLE_PODCASTS] to filter by multiple platforms.

Filter by Podcast Count​

Filter categories by the number of podcasts they contain:

query {
    categories(filters: { podcastCount: { from: 100, to: 1000 } }, first: 25) {
        data {
            title
            slug
            podcastCount
        }
    }
}

You can use from to set a minimum count, to to set a maximum count, or both to create a range.

Combining Filters​

You can combine multiple filters to find specific categories:

query {
    categories(
        searchTerm: "business",
        filters: {
            inCharts: [APPLE_PODCASTS],
            podcastCount: { from: 100 }
        },
        first: 25
    ) {
        data {
            title
            slug
            podcastCount
            chartPlatforms
        }
    }
}

This query will find categories matching "business" that are available on Apple Podcasts charts and have at least 100 podcasts.

Using Category Slugs to Filter Podcasts​

Once you have found a category, you can use its slug to filter podcasts. The category slug can be used in the categories filter of the podcasts query:

# First, find a category
query {
    categories(searchTerm: "technology", first: 25) {
        data {
            slug
        }
    }
}
    
# Then use the slug to filter podcasts
query {
    podcasts(filters: { categories: ["technology"] }, first: 25) {
        data {
            title
            description
        }
    }
}

Pagination​

The categories query supports pagination using the first and page arguments:

  • first: The number of items to return per page (required, must be greater than 0)
  • page: The page number to retrieve (0-indexed, defaults to 0)
query {
    categories(first: 10, page: 1) {
        paginatorInfo {
            count
            currentPage
            hasMorePages
            lastPage
            perPage
            total
        }
        data {
            title
            slug
            podcastCount
        }
    }
}

The paginatorInfo object provides:

  • count: Number of items in the current page
  • currentPage: The current page number (0-indexed)
  • hasMorePages: Boolean indicating if there are more pages
  • lastPage: The last page number (0-indexed)
  • perPage: Number of items per page
  • total: Total number of items across all pages

Category Fields​

Each category in the results includes:

  • title: The display name of the category
  • slug: A URL-friendly identifier used for filtering podcasts
  • podcastCount: The number of podcasts in this category (from Elasticsearch)
  • chartPlatforms: An array of chart platforms that have this category (APPLE_PODCASTS, SPOTIFY) (from Elasticsearch)

Here's an example that finds the most popular categories (by podcast count):

query {
    categories(sort: { sortBy: PODCAST_COUNT, direction: DESCENDING }, first: 25) {
        paginatorInfo {
            total
        }
        data {
            title
            slug
            podcastCount
        }
    }
}

This will return categories sorted from highest to lowest podcast count, helping you discover the most popular categories in Podchaser.