---
title: "Returns a paged list of categories and provides search functionality."
url: "https://developer-qual.migros.ch/apis/categories-8/versions/8ce90ed3-19b1-4b6b-9012-a509d9212a56/operations/get-categories"
---

> Full API specification: https://developer-qual.migros.ch/apis/categories-8/versions/8ce90ed3-19b1-4b6b-9012-a509d9212a56.md

# Returns a paged list of categories and provides search functionality.

`GET` `/migros/products/v8/categories`

Operation ID: `get-categories`

Returns a paged list of categories and provides search functionality.

## Query parameters

- `search` (string, optional) - Simple search string which is fault-tolerant for user-entered text.
- `limit` (integer, optional) - Maximum number of results (max 2000).
- `offset` (integer, optional) - Result set offset.
- `sort` (string, optional) - The sorting criteria.
- `order` (string, optional) - The ordering direction.
- `ids` (string, optional) - A comma separated list or an array of category ids defining the categories and the order in which the categories should be returned. If the ids parameter is provided all other filtering parameters are ignored.
- `view` (string, optional) - Show specific set of categories, where 'browse': limit to categories that should be shown, and 'browseallretailers': limit to categories that should be shown, but include additional retailers like Alnatura.
- `custom_image` (boolean, optional) - Whether to output the custom image format with placeholders for width and height.
- `lang` (string, optional) - Defines the language (de/fr/it/en) for this request as query parameter. Either use the query param "lang" or header "Accept-Language", not both.

## Header parameters

- `Accept-Language` (string, optional) - Defines the language (de/fr/it/en) for this request as request header. Either use the query param "lang" or header "Accept-Language", not both.

## Responses

- `200` - Returned when successful
- `400` - If the request parameters are invalid.

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Categories
  version: "8"
servers:
  - description: Public Kong Gateway URL
    url: https://api-qual.migros.ch
paths:
  /migros/products/v8/categories:
    get:
      description: Returns a paged list of categories and provides search functionality.
      operationId: get-categories
      parameters:
        - $ref: "#/components/parameters/search"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - description: The sorting criteria.
          in: query
          name: sort
          schema:
            default: score
            enum:
              - score
              - code
              - category
              - name
            type: string
        - $ref: "#/components/parameters/order"
        - description: A comma separated list or an array of category ids defining the
            categories and the order in which the categories should be returned.
            If the ids parameter is provided all other filtering parameters are
            ignored.
          in: query
          name: ids
          schema:
            type: string
        - description: "Show specific set of categories, where 'browse': limit to
            categories that should be shown, and 'browseallretailers': limit to
            categories that should be shown, but include additional retailers
            like Alnatura."
          in: query
          name: view
          schema:
            default: browse
            enum:
              - browse
              - browseallretailers
            type: string
        - $ref: "#/components/parameters/custom_image"
        - $ref: "#/components/parameters/lang"
        - $ref: "#/components/parameters/Accept-Language"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CategoryCollection"
          description: Returned when successful
        "400":
          $ref: "#/components/responses/400"
      summary: Returns a paged list of categories and provides search functionality.
      tags:
        - Categories
security:
  - Kong-Api-Key: []
    basicAuth: []
components:
  parameters:
    search:
      description: Simple search string which is fault-tolerant for user-entered text.
      in: query
      name: search
      required: false
      schema:
        type: string
    limit:
      description: Maximum number of results (max 2000).
      in: query
      name: limit
      required: false
      schema:
        default: 10
        maximum: 2000
        minimum: 0
        type: integer
    offset:
      description: Result set offset.
      in: query
      name: offset
      required: false
      schema:
        default: 0
        minimum: 0
        type: integer
    order:
      description: The ordering direction.
      in: query
      name: order
      schema:
        default: asc
        enum:
          - asc
          - desc
        type: string
    custom_image:
      description: Whether to output the custom image format with placeholders for
        width and height.
      in: query
      name: custom_image
      schema:
        default: false
        type: boolean
    lang:
      description: Defines the language (de/fr/it/en) for this request as query
        parameter. Either use the query param "lang" or header
        "Accept-Language", not both.
      in: query
      name: lang
      schema:
        default: de
        enum:
          - de
          - fr
          - it
          - en
        type: string
    Accept-Language:
      description: Defines the language (de/fr/it/en) for this request as request
        header. Either use the query param "lang" or header "Accept-Language",
        not both.
      in: header
      name: Accept-Language
      schema:
        default: de
        enum:
          - de
          - fr
          - it
          - en
        type: string
  schemas:
    CategoryCollection:
      allOf:
        - $ref: "#/components/schemas/AbstractSearchResultCollection"
        - properties:
            categories:
              items:
                $ref: "#/components/schemas/Category"
              type: array
          type: object
      description: A collection of category instances.
      required:
        - categories
        - total_hits
      type: object
    AbstractSearchResultCollection:
      allOf:
        - $ref: "#/components/schemas/AbstractCollection"
        - properties:
            ids:
              description: >-
                Ids only.


                Is filled instead of the usual property for content, with only
                the ids when a call is made with verbosity=id on a

                route that supports it.
              items:
                type: string
              type: array
            total_hits:
              description: >-
                The total hits may exceed the actual count of results in the
                collection.


                It represents the total number of results of a search and not
                only the

                potentially paginated subset.
              nullable: true
              type: integer
          type: object
      description: A collection of search result instances.
      type: object
    Category:
      allOf:
        - $ref: "#/components/schemas/BaseCategory"
        - properties:
            ancestors:
              description: Collection of ancestor categories.
              items:
                $ref: "#/components/schemas/BaseCategory"
              nullable: true
              type: array
            children:
              description: >-
                Collection of child categories.


                Children include only direct children (categories of the next
                level).
              items:
                $ref: "#/components/schemas/BaseCategory"
              nullable: true
              type: array
            generic_products:
              description: >-
                List of generic product BoSS numbers.


                The BoSS number from the BoSS/BeSS mapping, so that the app can
                query for categories by BoSS number.
              items:
                type: string
              nullable: true
              type: array
            google_product_categories:
              description: |-
                List of google taxonomy IDs this category maps to.

                See https://support.google.com/merchants/answer/6324436?hl=en and https://www.google.com/basepages/producttype/taxonomy-with-ids.de-CH.txt
                It's based on the field "googletaxonomy" coming from PEx.
              items:
                type: string
              nullable: true
              type: array
            slugs:
              $ref: "#/components/schemas/Slugs"
            updated_at:
              description: >-
                Time when category was last indexed (or partially updated) with
                modifications in Elasticsearch.


                When a category did not change after mapping, it is not
                re-indexed and thus the timestamp is not updated as well.
              format: date-time
              nullable: true
              type: string
            visible_navigation:
              description: >-
                If set to false, the category should not be displayed in
                navigation, but may still be displayed in

                search suggestions or similiar (e.g. 'Fussball EM 2016').


                It's based on the same field coming from PEx.
              type: boolean
            visible_shop:
              description: >-
                If set to false, the category should not be displayed anywhere
                (e.g. 'Dienstleistungen').


                It's based on the same field coming from PEx.
              type: boolean
          type: object
      description: Represents the category information including its ancestors and children.
      required:
        - code
        - name
        - slug
        - slugs
        - updated_at
      type: object
    AbstractCollection:
      description: A generic collection of elements.
    BaseCategory:
      description: Represents the category basic information.
      properties:
        abstract:
          description: A short, plain text description, e.g. suitable for the page meta
            element.
          nullable: true
          type: string
        code:
          description: ID of the category.
          type: string
        headline:
          description: The caption to the description.
          nullable: true
          type: string
        image:
          description: Image of the category.
          nullable: true
          oneOf:
            - $ref: "#/components/schemas/Image"
        keywords:
          description: Keywords, e.g. suitable for the page meta element.
          items:
            type: string
          nullable: true
          type: array
        level:
          description: Category level.
          type: integer
        name:
          type: string
        parent_code:
          description: Parent category ID.
          nullable: true
          type: string
        slug:
          description: Unique user-friendly ID.
          type: string
        title:
          description: The title, e.g. suitable for the page title element.
          nullable: true
          type: string
        visible:
          description: Whether the category should be shown to users.
          type: boolean
      required:
        - code
        - name
        - slug
      type: object
    Slugs:
      description: Represents a list of multilingual slugs.
      properties:
        de:
          description: Slug in English.
          type: string
        en:
          type: string
        fr:
          type: string
        it:
          type: string
      required:
        - de
        - fr
        - it
        - en
      type: object
    Image:
      description: An image and its properties.
      properties:
        code:
          deprecated: true
          description: Code for the image, useful for pictograms.
          nullable: true
          type: string
        custom:
          deprecated: true
          description: Image URL with placeholders for {width} and {height}.
          type: string
        description:
          deprecated: true
          description: Image description, useful for example as alt attribute.
          nullable: true
          type: string
        end_date:
          deprecated: true
          description: End date of the validity.
          format: date-time
          nullable: true
          type: string
        hash:
          deprecated: true
          description: Sha1 hash of original image.
          nullable: true
          type: string
        original:
          deprecated: true
          description: Full size image.
          type: string
        source:
          deprecated: true
          description: Source where the image comes from originally.
          nullable: true
          type: string
        stack:
          deprecated: true
          description: Image URL with a placeholder for a Rokka {stack}.
          type: string
        start_date:
          deprecated: true
          description: Start date of the validity.
          format: date-time
          nullable: true
          type: string
        tags:
          deprecated: true
          items:
            type: string
          type: array
      type: object
  responses:
    "400":
      description: If the request parameters are invalid.
  securitySchemes:
    Kong-Api-Key:
      description: Kong key-auth authentication
      in: header
      name: X-Api-Key
      type: apiKey
    basicAuth:
      scheme: basic
      type: http
```