> ## Documentation Index
> Fetch the complete documentation index at: https://partner.headout.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List all subcategories

Retrieve subcategories within each main category for a specific city (e.g., "Museums", "Landmarks", "Religious Sites" under "Tickets"). Subcategories provide finer-grained filtering options for product discovery and help users navigate to specific experience types. Results are ordered by subcategory rank. Use the returned IDs as `subCategoryId` in the [Products endpoint](/docs/affiliate/v2/products).

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --location 'https://www.headout.com/api/public/v2/subcategories/?cityCode=<CITY_CODE>&languageCode=<LANGUAGE_CODE>' \
  --header 'Headout-Auth: <YOUR_API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "subCategories": [
      {
        "id": "1002",
        "name": "Museums",
        "categoryId": "1",
        "canonicalUrl": "https://www.headout.com/museums-new_york-sc-1002~21553/",
        "localeSpecificUrls": {
          "EN": "/museums-new_york-sc-1002~21553/",
          "ES": "/es/museos-new_york-sc-1002~21553/",
          "FR": "/fr/musees-new_york-sc-1002~21553/",
          "IT": "/it/musei-new_york-sc-1002~21553/",
          "DE": "/de/museen-new_york-sc-1002~21553/",
          "PT": "/pt/museus-new_york-sc-1002~21553/",
          "NL": "/nl/musea-new_york-sc-1002~21553/"
        }
      },
      {
        "id": "1001",
        "name": "Theme Parks",
        "categoryId": "1",
        "canonicalUrl": "https://www.headout.com/theme-parks-new_york-sc-1001~21553/",
        "localeSpecificUrls": {
          "EN": "/theme-parks-new_york-sc-1001~21553/",
          "ES": "/es/parques-tematicos-new_york-sc-1001~21553/",
          "FR": "/fr/parcs-a-theme-new_york-sc-1001~21553/",
          "IT": "/it/parchi-a-tema-new_york-sc-1001~21553/",
          "DE": "/de/freizeitparks-new_york-sc-1001~21553/",
          "PT": "/pt/parques-tematicos-new_york-sc-1001~21553/",
          "NL": "/nl/pretparken-new_york-sc-1001~21553/"
        }
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /api/public/v2/subcategories/
openapi: 3.1.0
info:
  title: Headout API Docs - Common v2
  version: 0.0.1
servers:
  - url: https://www.headout.com
    description: Production server
  - url: https://www.sandbox-headout.com
    description: Sandbox server
security: []
paths:
  /api/public/v2/subcategories/:
    get:
      tags:
        - Subcategories
      summary: List all subcategories
      operationId: v2ListSubcategories
      parameters:
        - $ref: '#/components/parameters/cityCode'
        - $ref: '#/components/parameters/languageCode'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2Subcategories'
      security:
        - apiKeyAuth: []
components:
  parameters:
    cityCode:
      name: cityCode
      in: query
      required: true
      schema:
        type: string
      description: >-
        Uppercase city identifier (e.g., `NEW_YORK`, `DUBAI`, `LONDON`).
        Available city codes are returned by the Cities endpoint.
    languageCode:
      name: languageCode
      in: query
      schema:
        type: string
        default: EN
        enum:
          - EN
          - ES
          - FR
          - IT
          - DE
          - PT
          - NL
          - PL
          - KO
          - JA
          - ZH_HANS
          - ZH_HANT
          - AR
          - DA
          - false
          - RO
          - RU
          - SV
          - TR
      description: >-
        Language code for localizing response content including product names,
        descriptions, and URLs. Defaults to English (`EN`). Content falls back
        to English when a translation is unavailable. See [supported language
        codes](/guide/enums-and-error-codes#language-codes).
  schemas:
    V2Subcategories:
      type: object
      properties:
        subCategories:
          type: array
          items:
            $ref: '#/components/schemas/V2SubCategory'
          description: All subcategories available in the requested city.
    V2SubCategory:
      type: object
      properties:
        id:
          type: string
          description: >-
            Headout's identifier for this subcategory. Use as the
            `subCategoryId` filter in the Products endpoint.
        name:
          type: string
          description: >-
            Display name of the subcategory (e.g., "Museums", "Landmarks",
            "Religious Sites").
        categoryId:
          type: string
          description: Identifier of the parent category this subcategory belongs to.
        canonicalUrl:
          type: string
          description: >-
            The canonical Headout URL for this subcategory page, suitable for
            linking and SEO.
        localeSpecificUrls:
          type: object
          additionalProperties:
            type: string
          description: >-
            Localized subcategory page URLs keyed by language code (`EN`, `ES`,
            `FR`, etc.).
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Headout-Auth

````