Follow guide ⏭️

GET /navigation/guide/{search_id}/{locale}/follow/{step}
Api key

This endpoint is the core of the guided search. It has a double use case:

  • Get a question of a given step with possible choices
  • Answer to a question of a given step with user choices, in that case the next question + choices is returned directly

It is meant to be used several times in a row to follow the guide until the end, or until the user wants to stop it and show results immediately

Path parameters

  • search_id string Required

    The search_id as returned by the Initialize guide endpoint.

  • locale string Required

    The locale in which to go through the guide. It can be changed at any step of the guide. Available languages depend on your corporation settings.

    Value is en fr it es de hu ja be pt es fi ro tr pt-BR es-AR.

  • step string Required

    The step for which we want to get the question or the step we want to answer to. If you're not answering a given step, use current to automatically jump to latest step.

Query parameters

  • choice_key string

    The string representation of the choice(s) made by the user for the question at the given step.
    For multiple choices, allowed combinations are given by available_combination_mode attribute of the question.
    In order to build the final choice_key, you'll need to concatenate the choice keys with

    • ~ char for and combination
    • | char for or combination

    If the question is marked as skippable, it can be skipped by using skip as a choice

    If you want to go back to the previous proposed question, you should use back as a choice

Responses

  • • 200 object

    Submit choices for a given question, and get next question with its choices

    • status string
    • result object
      • context object
        • locale string

          Available languages depend on your corporation settings

          Value is en fr it es de hu ja be pt es fi ro tr pt-BR es-AR.

        • search_id string

          The search_id include all user choices, built or edited at each stage of the search guide

        • custom_pictos_only boolean

          True if only custom pictograms are returned, but not Deck default pictograms

        • step integer

          The current step of the search, to be used to identify the question we're answering to

        • product_count integer

          Total product count at current step

        • api_follow_guide url

          The API endpoint to follow search guide while there are still some steps to follow

        • api_refine_guide url

          The API endpoint to refine your search once you followed all the steps

        • api_guide_results url

          The API endpoint to get search guide results

      • question object
        • key string

          Unique key to identify the question

        • label string

          Question key translation (depending of the locale)

        • available_combination_mode string

          The different ways that several answers for this question can be combined:

          • "none" --> Single choice, no combination possible
          • "or" --> Multiple choice, only with OR combination --> "choice_1|choice_2"
          • "and_or" --> Multiple choice, with AND or OR combinations --> "choice_1~choice_2" OR "choice_1|choice_2"
        • picto_url string

          The URL of the question pictogram

        • is_back_allowed boolean

          Wether or not this question can be rollback

        • is_skip_allowed boolean

          Wether or not this question can be skipped

      • choices array[object]
        • key string

          Unique key to identify the choice

        • label string

          Choice key translation (depending of the locale)

        • picto_url string

          The URL of the choice pictogram

        • product_count integer

          The number of products affected by this choice

GET /navigation/guide/{search_id}/{locale}/follow/{step} 
curl \
 -X GET https://api.ppe-analytics.com/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/follow/2 \
 -H "PPEApiKey: $API_KEY"
Response example (200) 
{
  "status": "OK",
  "result": {
    "context": {
      "locale": "it",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "custom_pictos_only": true,
      "step": 2,
      "product_count": 262,
      "api_follow_guide": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/follow/3",
      "api_guide_results": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/results",
      "api_skip_question": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/follow/3?choice_key=_skip_",
      "api_back_question": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/follow/3?choice_key=_back_"
    },
    "question": {
      "key": "search-by-manufacturer",
      "label": "Ricerca per produttore",
      "available_combination_mode": "or",
      "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg",
      "is_back_allowed": true,
      "is_skip_allowed": true
    },
    "choices": [
      {
        "key": "manufacturer-1",
        "label": "Produttore n°1",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg",
        "product_count": 20
      },
      {
        "key": "manufacturer-2",
        "label": "Produttore n°2",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a39585.jpg",
        "product_count": 55
      },
      {
        "key": "manufacturer-3",
        "label": "Produttore n°3",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a39585.jpg",
        "product_count": 187
      }
    ]
  }
}