Deck API
1.0.0-beta

This is the official Deck API documentation.
Deck API allows you to access product information from your corporation product perimeter.

This is the documentation for version 1.0.0-beta of the API. Last update on Sep 2, 2022.

Base URL
https://api.ppe-analytics.com/api/v1

Authentication

Api key (http_api_key)

🛡️ Deck API access is restricted to Deck customers and partners.

In order to access the API, you'll need to authenticate by sending your authentication token in the PPEApiKey header of your requests.
Access rights and product perimeters depend on the API key provided, so you may have to use several API keys if you work on several projects with different scopes.

👉 If you need an API key to look around and try our API, ask one here.

👉 If you want to use Deck services or become a partner, contact us on support@ppe-analytics.com.


List segments

GET /segments

Returns the list of segments available to your corporation.

A segment is a product family in which the products share common technical properties and where comparison between them make sense.

Each segment has a customized data model, allowing for very fine definition without bothering products from other segments with properties that would never be used.

Responses
  • 200 object

    Successfully returned available segments

    • status string
    • result object
      • segments array[object]
        • key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • picto_url string

          The URL of the pictogram for the segment.

        • The API endpoint to get all available properties of the segment

        • The API endpoint to get all available products of the segment

        • trads object

          Translations for the object. Available languages depend on your corporation settings

          • en string
          • fr string
GET /segments
curl \
 -X GET https://api.ppe-analytics.com/api/v1/segments \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "segments": [
      {
        "key": "head-protection",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300w/epi-head.png",
        "api_get_properties": "/api/v1/segments/hand-protection",
        "api_get_products": "/api/v1/products/hand-protection",
        "trads": {
          "en": "Head protection",
          "fr": "Protection de la tête"
        }
      },
      {
        "key": "fall-protection",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300w/epi-head.png",
        "api_get_properties": "/api/v1/segments/head-protection",
        "api_get_products": "/api/v1/segments/head-protection",
        "trads": {
          "en": "Fall protection",
          "fr": "Protection antichute"
        }
      }
    ]
  }
}

Fetch segment data model

GET /segments/{segment_key}

The data model of a segment consists of several properties identified by their key. Each property has a type depending on the data it can contain.

Several types are available: boolean, string, enum, enum_list, json, arbo_enum, arbo_enum_list

In the case of types enum and enum_list, the list of possible values is provided, identified by their key.

Path parameters
  • segment_key Required / string

    The segment key, as returned by the List segments endpoint.

    Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

Responses
  • 200 object

    Successfully returned segment data model

    • status string
    • result object
      • segment object
        • key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • picto_url string

          The URL of the pictogram for the segment.

        • The API endpoint to get all available properties of the segment

        • The API endpoint to get all available products of the segment

        • trads object

          Translations for the object. Available languages depend on your corporation settings

          • en string
          • fr string
      • languages array[string]

        Available languages depend on your corporation settings

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

      • properties array[object]
        • key string

          The slug to identify the property. It is unique segment-wise.

        • type string

          Type of the data handled by the property.

          Values are boolean string enum enum_list json arbo_enum arbo_enum_list.

        • group string

          The group key of this property, mostly for organisation purpose.

        • picto_url url

          The URL of the pictogram for the property.

        • trads object

          Translations for the object. Available languages depend on your corporation settings

          • en string
          • fr string
        • values array[object]

          The available values for this property (only for enum and enum_list types).

          • key string

            The slug for this value. It is unique property-wise.

          • rank integer

            The rank of the value within its siblings

          • picto_url url

            The URL of the pictogram for the value.

          • trads object

            Translations for the object. Available languages depend on your corporation settings

            • en string
            • fr string
  • 404 object

    Unknown segment key

  • 403 object

    Unauthorized segment

GET /segments/{segment_key}
curl \
 -X GET https://api.ppe-analytics.com/api/v1/segments/surface-cleaning \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "segment": {
      "key": "hand-protection",
      "picto_url": "https://app.ppe-analytics.com/static/pictos/300w/epi-hand.png",
      "api_get_properties": "/api/v1/segments/hand-protection",
      "api_get_products": "/api/v1/products/hand-protection",
      "trads": {
        "en": "Hand protection",
        "fr": "Protection de la main"
      }
    },
    "languages": [
      "en fr it es"
    ],
    "properties": [
      {
        "key": "color",
        "group": "description",
        "type": "enum_list",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300w/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg",
        "trads": {
          "en": "Color",
          "fr": "Couleur",
          "de": "Farbe"
        },
        "values": [
          {
            "key": "red",
            "rank": 1,
            "picto_url": "https://app.ppe-analytics.com/static/pictos/150w/e32e0f84-7889-414d-ab17-3be2d1f47f9a.jpg",
            "trads": {
              "en": "Red",
              "fr": "Rouge",
              "de": "Rot"
            }
          },
          {
            "key": "green",
            "rank": 2,
            "picto_url": "https://app.ppe-analytics.com/static/pictos/150w/5872a29a-0059-4342-82cc-cb1e1965d629.jpg",
            "trads": {
              "en": "Green",
              "fr": "Vert",
              "de": "Grün"
            }
          }
        ]
      }
    ]
  }
}
Response example (404)
{
  "status": "ERROR",
  "message": "Unknown segment key 'book-protection'"
}
Response example (403)
{
  "status": "ERROR",
  "message": "Unauthorized access to segment 'secret-agent'"
}

List products

GET /products/{segment_key}

Returns the list of products available to your corporation for a given segment.

Only basic product information is provided by this endpoint, including product id. Full information is available through the Fetch product information endpoint

Path parameters
  • segment_key Required / string

    The segment key of the product, as returned by list products endpoint.

    Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

Responses
  • 200 object

    Successfully returned products

    • status string
    • result object
      • products array[object]
        • segment_key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • id string

          Id to identify the product, unique segment-wise

        • name string

          The name of the product

        • Date of last modification on product

        • The API endpoint to get all information on the product

        • The URL of the main picture for the product

        • The URL of the public product page

  • 404 object

    Unknown segment key

  • 403 object

    Unauthorized segment

GET /products/{segment_key}
curl \
 -X GET https://api.ppe-analytics.com/api/v1/products/surface-cleaning \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "products": [
      {
        "segment_key": "surface-cleaning",
        "id": "f50938a24830edb8b1c2ecc3f7dd88a3",
        "name": "Apollo 1027",
        "last_modified": "2022-06-24 17:14:46 +0200",
        "api_get_product": "/api/v1/product/surface-cleaning/f50938a24830edb8b1c2ecc3f7dd88a3",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/surface-cleaning/f50938a24830edb8b1c2ecc3f7dd88a3.jpg"
      },
      {
        "segment_key": "surface-cleaning",
        "id": "89e6848c8f1f91404c224393340b1fad",
        "name": "Ariane Ultra 1212",
        "last_modified": "2022-06-22 10:04:02 +0200",
        "api_get_product": "/api/v1/product/surface-cleaning/89e6848c8f1f91404c224393340b1fad",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/surface-cleaning/89e6848c8f1f91404c224393340b1fad.jpg"
      }
    ]
  }
}
Response example (404)
{
  "status": "ERROR",
  "message": "Unknown segment key 'book-protection'"
}
Response example (403)
{
  "status": "ERROR",
  "message": "Unauthorized access to segment 'secret-agent'"
}

Fetch product information

GET /products/{segment_key}/{product_id}

Get all information about a product:

  • descriptions in multiple languages - name / long description / short description
  • picture URLs - main picture + additional pictures
  • documents in multiple languages - technical sheet, manuals, CE certificates...
  • property values - as defined by segment data model
  • SKUs - logistic references for products
Path parameters
  • segment_key Required / string

    The segment key, as returned by list segments endpoint.

    Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

  • product_id Required / string

    The unique product id, as returned by list products endpoint.

Responses
  • 200 object

    Successfully returned product information

    • status string
    • result object
      • languages array[string]

        Available languages depend on your corporation settings

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

      • product object
        • segment_key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • id string

          Id to identify the product, unique segment-wise

        • name string

          The name of the product

        • The URL of the main picture for the product

        • Localized URLs for the object. Available languages depend on your corporation settings

          • en string
          • fr string
        • description object
          • name object

            Translations for the object. Available languages depend on your corporation settings

            • en string
            • fr string
          • description object

            Translations for the object. Available languages depend on your corporation settings

            • en string
            • fr string
          • Translations for the object. Available languages depend on your corporation settings

            • en string
            • fr string
        • pictures array[object]
        • documents object

          The list of available types used as keys depend on your corporation settings and on the content attached to the product

          • Localized URLs for the object. Available languages depend on your corporation settings

            • en string
            • fr string
          • Localized URLs for the object. Available languages depend on your corporation settings

            • en string
            • fr string
        • values object
          • property_key string

            To be replaced with the property key of the property

          • value string

            The value for this property can be:

            • a value_key for enum
            • an array of value_key for enum_list
            • a string otherwise
        • skus array[object]

          The list of active SKUs on this product

          • code string

            The unique code for the SKU

          • label string

            A description for this SKU

        • countries array[string]

          The list of countries in which the product is sold, using alpha-2 iso codes

  • 404 object

    Unknown product id

  • 403 object

    Unauthorized product

GET /products/{segment_key}/{product_id}
curl \
 -X GET https://api.ppe-analytics.com/api/v1/products/surface-cleaning/cbdeacabd0128cb641b64d0c0f590332 \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "languages": [
      "en",
      "fr"
    ],
    "product": {
      "segment_key": "surface-cleaning",
      "id": "f50938a24830edb8b1c2ecc3f7dd88a3",
      "name": "Apo-low 1027",
      "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/surface-cleaning/f50938a24830edb8b1c2ecc3f7dd88a3.jpg",
      "product_page_urls": {
        "en": "https://website.uk/product-64654",
        "fr": "https://website.fr/produit-64654"
      },
      "description": {
        "name": {
          "en": "Apo-low 1027",
          "fr": "Apo-bas 1027"
        },
        "description": {
          "en": "This product is truly awesome and made for you",
          "fr": "Ce produit est vraiment incroyable et pensé pour vous"
        },
        "short_description": {
          "en": "You deserve the best",
          "fr": "La meilleure qualité pour vous"
        }
      },
      "pictures": [
        {
          "square-80px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/80/89033e1b-3491-4780-86aa-52b56a7642f9.png",
          "square-300px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/300/89033e1b-3491-4780-86aa-52b56a7642f9.png",
          "square-600px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/600/89033e1b-3491-4780-86aa-52b56a7642f9.png",
          "original": "https://app.ppe-analytics.com/static/asset-pictures/mapa/original/89033e1b-3491-4780-86aa-52b56a7642f9.png",
          "is_main_picture": true
        },
        {
          "square-80px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/80/8e39821f-e743-4b70-8db9-2f2513c8499b.png",
          "square-300px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/300/8e39821f-e743-4b70-8db9-2f2513c8499b.png",
          "square-600px": "https://app.ppe-analytics.com/static/asset-pictures/mapa/600/8e39821f-e743-4b70-8db9-2f2513c8499b.png",
          "original": "https://app.ppe-analytics.com/static/asset-pictures/mapa/original/8e39821f-e743-4b70-8db9-2f2513c8499b.png"
        }
      ],
      "documents": {
        "technical-sheet": {
          "en": "https://spontex.ppe-analytics.com/en/product/f50938a24830edb8b1c2ecc3f7dd88a3/pdf/technical-sheet",
          "fr": "https://spontex.ppe-analytics.com/fr/product/f50938a24830edb8b1c2ecc3f7dd88a3/pdf/technical-sheet"
        },
        "dcue-certificate": {
          "en": "https://spontex.ppe-analytics.com/en/product/f50938a24830edb8b1c2ecc3f7dd88a3/pdf/dcue-certificate",
          "fr": "https://spontex.ppe-analytics.com/fr/product/f50938a24830edb8b1c2ecc3f7dd88a3/pdf/dcue-certificate"
        }
      },
      "values": {
        "color": [
          "blue",
          "green",
          "black"
        ],
        "main-color": [
          "blue"
        ],
        "has-latex": true,
        "en388-digits": "4343X"
      },
      "skus": [
        {
          "code": "APO1027-123",
          "label": "APO-LOW 1027 polybag"
        },
        {
          "code": "APO1027-456",
          "label": "APO-LOW 1027 single"
        },
        {
          "code": "APO1027-777",
          "label": "APO-LOW 1027 FOR EXPORT"
        }
      ],
      "countries": [
        "it",
        "fr",
        "gb",
        "ml"
      ]
    }
  }
}
Response example (404)
{
  "status": "ERROR",
  "message": "Unknown product id 'abcdef-1234'"
}
Response example (403)
{
  "status": "ERROR",
  "message": "Unauthorized access to product 'secret-agent/007'"
}

Search products

POST /products/search

Returns the list of products and product families available to your corporation, with their name matching a given input text.

Only basic product information is provided by this endpoint, including product id. Additional info can be reached through the links provided in basic information.

Body

The search request infos

  • input_text string

    The text to search for, typically from user input

  • max_count integer

    The maximum number of results to return

    Default value is 10.

  • language string

    Available languages depend on your corporation settings

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

Responses
  • 200 object

    Successfully returned products (can be empty if no results)

    • status string
    • result object
      • products array[object]
        • segment_key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • id string

          Id to identify the product, unique segment-wise

        • name string

          The name of the product

        • Date of last modification on product

        • The API endpoint to get all information on the product

        • The URL of the main picture for the product

        • The URL of the public product page

      • families array
POST /products/search
curl \
 -X POST https://api.ppe-analytics.com/api/v1/products/search \
 -H "PPEApiKey: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"input_text":"Awesome 123","max_count":20,"language":"it"}'
Request example
{
  "input_text": "Awesome 123",
  "max_count": 20,
  "language": "it"
}
Response example (200)
{
  "status": "OK",
  "result": {
    "products": [
      {
        "segment_key": "lightening",
        "id": "f50938a24830edb8b1c2ecc3f7dd88a3",
        "name": "Awesome light 123",
        "last_modified": "2022-06-24 17:14:46 +0200",
        "api_get_product": "/api/v1/product/lightening/f50938a24830edb8b1c2ecc3f7dd88a3",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/lightening/f50938a24830edb8b1c2ecc3f7dd88a3.jpg",
        "product_page_url": "https://my-website.it/lightening/f50938a24830edb8b1c2ecc3f7dd88a3"
      },
      {
        "segment_key": "head-protection",
        "id": "89e6848c8f1f91404c224393340b1fad",
        "name": "Awesome helmet 1234",
        "last_modified": "2022-06-22 10:04:02 +0200",
        "api_get_product": "/api/v1/product/head-protection/89e6848c8f1f91404c224393340b1fad",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/head-protection/89e6848c8f1f91404c224393340b1fad.jpg",
        "product_page_url": "https://my-website.it/head-protection/89e6848c8f1f91404c224393340b1fad"
      }
    ],
    "families": []
  }
}

List navigation trees

GET /navigation/trees

Returns the list of navigation trees available to your corporation.

A navigation tree is a tree-structure to organize your products and navigate into them in a classic "nested folders" architecture.

Responses
  • 200 object

    Successfully returned available navigation trees

    • status string
    • result object
      • navigation_trees array[object]
        • id string

          The unique id of the navigation tree

        • key string

          A key identifying the navigation tree, for understanding purpose, not guaranteed unique

        • Whether or not a product can be located in multiple nodes of the tree

        • The API endpoint to get the content of this navigation tree

GET /navigation/trees
curl \
 -X GET https://api.ppe-analytics.com/api/v1/navigation/trees \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "navigation_trees": [
      {
        "id": "aada9924-34dd-4ce7-8e15-482ff0c8fa81",
        "key": "by-risk",
        "allow_multiple_nodes": false,
        "api_get_navigation_tree": "/api/v1/navigation/trees/aada9924-34dd-4ce7-8e15-482ff0c8fa81"
      },
      {
        "id": "b1702cb8-b68e-47e5-a8fe-4a1b330d567f",
        "key": "website-tree-structure",
        "allow_multiple_nodes": true,
        "api_get_navigation_tree": "/api/v1/navigation/trees/b1702cb8-b68e-47e5-a8fe-4a1b330d567f"
      }
    ]
  }
}

Get navigation tree

GET /navigation/trees/{tree_id}

Returns the content of a given navigation tree.

A navigation tree is a tree-structure to organize your products and navigate into them in a classic "nested folders" architecture.

It is very different from the navigation guide whose structure is dynamic and depends on the population considered and the answers chosen previously.

The depth of the tree is not fixed, and can vary accross a given tree depending on the branches.

Some trees allow for products to be found in multiple nodes, whereas some others will enforce a unicity constraint. This is detailed via the allow_multiple_nodes attribute

For all the nodes with a parent_node_id, the API guarantees that the parent node is returned before any of its children in the list, allowing a single-pass parsing of the tree.

Path parameters
  • tree_id Required /

    The navigation tree id, as returned by list navigation trees endpoint.

Query parameters
  • The max depth to be returned for the tree. By default the full tree will be returned.

Responses
  • 200 object

    Successfully returned navigation tree content

    • status string
    • result object
        • id string

          The unique id of the navigation tree

        • key string

          A key identifying the navigation tree, for debugging/understanding purpose, not guaranteed unique

        • Whether or not a product can be located in multiple nodes of the tree

        • max_depth integer

          The max depth requested. -1 if no depth limit has been applied

        • nodes array[object]
          • id string

            The id of the node, unique accross the navigation tree

          • The id of the parent node (empty for root nodes)

          • key string

            A key identifying the node, for debugging/understanding purpose, not guaranteed unique

          • name object

            Translations for the object. Available languages depend on your corporation settings

            • en string
            • fr string
          • depth integer

            The depth of the node inside the tree

          • rank integer

            The ranking of the node accross its siblings

          • picto_urls array[url]

            The urls for the pictograms of this node (optional, not all nodes have pictograms)

  • 404 object

    Unknown navigation tree id

GET /navigation/trees/{tree_id}
curl \
 -X GET https://api.ppe-analytics.com/api/v1/navigation/trees/b1702cb8-b68e-47e5-a8fe-4a1b330d567f \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "navigation_tree": {
      "id": "b1702cb8-b68e-47e5-a8fe-4a1b330d567f",
      "key": "website-tree-structure",
      "allow_multiple_nodes": true,
      "max_depth": -1,
      "nodes": [
        {
          "id": "the-essentials",
          "key": "family~essentials",
          "name": {
            "en": "The essentials",
            "fr": "Les essentiels"
          },
          "depth": 1,
          "rank": 0,
          "picto_urls": [
            "https://app.ppe-analytics.com/static/pictos/300w/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg",
            "https://app.ppe-analytics.com/static/pictos/150w/e32e0f84-7889-414d-ab17-3be2d1f47f9a.jpg"
          ]
        },
        {
          "id": "on-sales",
          "key": "family~on-sales",
          "name": {
            "en": "On sales!",
            "fr": "Les promos"
          },
          "depth": 1,
          "rank": 1,
          "picto_urls": [
            "https://app.ppe-analytics.com/static/pictos/300w/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg"
          ]
        },
        {
          "id": "our-selection",
          "key": "family~our-selection",
          "depth": 1,
          "rank": 2,
          "name": {
            "en": "Our selection",
            "fr": "Notre selection"
          }
        },
        {
          "id": "indoor-work",
          "key": "env~indoor",
          "name": {
            "en": "Indoor work",
            "fr": "Travail en intérieur"
          },
          "depth": 2,
          "rank": 0,
          "parent_node_id": "the-essentials"
        },
        {
          "id": "outdoor-work",
          "key": "env~outdoor",
          "name": {
            "en": "Outdoor work",
            "fr": "Travail en exterieur"
          },
          "depth": 2,
          "rank": 1,
          "parent_node_id": "the-essentials"
        },
        {
          "id": "outdoor-work-cold",
          "key": "env-outdoor-temp~cold",
          "name": {
            "en": "Cold environment",
            "fr": "Environnement froid"
          },
          "depth": 3,
          "rank": 0,
          "parent_node_id": "outdoor-work"
        },
        {
          "id": "outdoor-work-hot",
          "key": "env-outdoor-temp~hot",
          "name": {
            "en": "Hot environment",
            "fr": "Environnement chaud"
          },
          "depth": 3,
          "rank": 1,
          "parent_node_id": "outdoor-work"
        }
      ]
    }
  }
}
Response example (404)
{
  "status": "ERROR",
  "message": "Unknown navigation tree id 'abcdef-1234'"
}

Initialize guide

POST /navigation/guide/init

Initialize a new guided search.

A guided search will take several steps to go through, thus it is identified by a search_id which must be provided at each step.

The search_id holds all user choices made at each step of the guide.

Responses
  • 200 object

    Successfully initialized guided search

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

          Available languages depend on your corporation settings

          Values are 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

        • 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 stel

        • The API endpoint to follow search guide

        • The API endpoint to get search guide results.

POST /navigation/guide/init
curl \
 -X POST https://api.ppe-analytics.com/api/v1/navigation/guide/init \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "context": {
      "locale": "en",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "step": 1,
      "product_count": 4513,
      "api_follow_guide": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/follow/current",
      "api_guide_results": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/results"
    }
  }
}

Follow guide

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

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 Required / string

    The search_id as returned by the Initialize guide endpoint.

  • locale Required / string

    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.

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

  • step Required / string

    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
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

          Values are 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

        • 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 stel

        • The API endpoint to follow search guide

        • 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)

        • 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

      • 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",
      "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"
    },
    "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"
    },
    "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
      }
    ]
  }
}

Guide results

GET /navigation/guide/{search_id}/{locale}/results

Get search results and search filters for the latest step of a given search.

It can be called at the end of the guide (when there is no question left) but can also be called any time during the guided search.

As the results can be a bit heavy, it is not recommended to call it at each step though.
product_count attribute should be used instead to provide some feedback about the current volume of the search

Path parameters
  • search_id Required / string

    The search_id as returned by the Follow guide endpoint.

  • locale Required / string

    The locale in which to receive the results. Available languages depend on your corporation settings.

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

Responses
  • 200 object

    Successfully returned results for a given search (filters + products)

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

          Available languages depend on your corporation settings

          Values are 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

        • 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 stel

        • The API endpoint to follow search guide

        • The API endpoint to get search guide results.

      • filters array[object]
        • segment_key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • key string

          Unique key to identify the filter

        • name string

          Filter key translation (depending of the locale)

        • The value for this property can be:

          • "none" --> Single choice
          • "and" OR "or" --> Multiple choice --> "choice_1~choice_2" OR "choice_1|choice_2"
        • picto_url string

          The URL of the filter pictogram

        • values array[object]
          • key string

            Unique key to identify the value

          • name string

            value key translation (depending of the locale)

          • picto_url string

            The URL of the value pictogram

      • products array[object]
        • segment_key string

          Unique slug to identify the segment

          Values are hand-protection, foot-protection, head-protection, eye-protection, body-protection, ear-protection, fall-protection, respiratory-protection, ergonomy, safety-first-aid, hygiene, lockout-tagout, electrical, lightening, safety-signs, or surface-cleaning.

        • id string

          Id to identify the product, unique segment-wise

        • name string

          The name of the product

        • Date of last modification on product

        • The API endpoint to get all information on the product

        • The URL of the main picture for the product

        • The URL of the public product page

GET /navigation/guide/{search_id}/{locale}/results
curl \
 -X GET https://api.ppe-analytics.com/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/it/results \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "result": {
    "context": {
      "locale": "fr",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "step": 4,
      "product_count": 50,
      "api_follow_guide": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/fr/follow/current"
    },
    "filters": [
      {
        "segment_key": "head-protection",
        "key": "colour",
        "name": "Couleur",
        "selected_combination_mode": "or",
        "picto_url": "https://app.ppe-analytics.com/static/pictures/300/head-protection/89e6848c8f1f91404c224393340b1fad.jpg",
        "values": [
          {
            "key": "white",
            "name": "Blanc",
            "picto_url": "https://app.ppe-analytics.com/static/pictures/300/head-protection/89e6848c8f1f91404c224393340b1fad.jpg"
          },
          {
            "key": "black",
            "name": "Noir",
            "picto_url": "https://app.ppe-analytics.com/static/pictures/300/head-protection/89e6848c8f1f91404c224393340b1fad.jpg"
          }
        ]
      }
    ],
    "products": [
      {
        "segment_key": "head-protection",
        "id": "f50938a24830edb8b1c2ecc3f7dd88a3",
        "name": "Awesome light 123",
        "api_get_product": "/api/v1/product/lightening/f50938a24830edb8b1c2ecc3f7dd88a3",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/lightening/f50938a24830edb8b1c2ecc3f7dd88a3.jpg",
        "product_page_url": "https://my-website.it/lightening/f50938a24830edb8b1c2ecc3f7dd88a3"
      },
      {
        "segment_key": "head-protection",
        "id": "89e6848c8f1f91404c224393340b1fad",
        "name": "Awesome helmet 1234",
        "api_get_product": "/api/v1/product/head-protection/89e6848c8f1f91404c224393340b1fad",
        "main_picture_url": "https://app.ppe-analytics.com/static/pictures/300/head-protection/89e6848c8f1f91404c224393340b1fad.jpg",
        "product_page_url": "https://my-website.it/head-protection/89e6848c8f1f91404c224393340b1fad"
      }
    ]
  }
}

Edit guide filter

GET /navigation/guide/{search_id}/{locale}/edit/{filter_key}

This endpoint allows to edit the values of a given filter as returned by the Guide results endpoint.

It has to be used in two calls:

  • The first one to get the possible choices, as well as the one already selected for the filter key
  • The second one to submit the new choices and get new products count

A call to the Guide results can be done afterwards to get the updated results

Path parameters
  • search_id Required / string

    The search_id as returned by the Guide results endpoint.

  • locale Required / string

    The locale in which to get the question and choices. Available languages depend on your corporation settings.

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

  • filter_key Required / string

    The filter_key to edit as provided by the Guide results endpoint

Query parameters
  • choice_key string

    The string representation of the choice(s) made by the user for the filter.
    For multiple choices, allowed combinations are given by available_combination_mode attribute of the filter.
    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
Responses
  • Get choices for the editer filter

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

          Available languages depend on your corporation settings

          Values are 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

        • 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 stel

        • The API endpoint to follow search guide

        • The API endpoint to get search guide results.

      • filter object
      • values array[object]
        • key string

          Unique key to identify the value

        • label string

          Choice key translation (depending of the locale)

        • picto_url url

          The URL of the value pictogram

        • is_selected boolean

          Whether or not this choice is already selected by the user

        • product_count integer

          The number of products resulting from this choice

  • The successfully response about the filter edition returns edited context

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

          Available languages depend on your corporation settings

          Values are 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

        • 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 stel

        • The API endpoint to follow search guide

        • The API endpoint to get search guide results.

GET /navigation/guide/{search_id}/{locale}/edit/{filter_key}
curl \
 -X GET https://api.ppe-analytics.com/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/edit/en407 \
 -H "PPEApiKey: $API_KEY"
Response example (200 - get filter choices)
{
  "status": "OK",
  "result": {
    "context": {
      "locale": "en",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "product_count": 75,
      "api_guide_results": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/results"
    },
    "filter": {
      "key": "en407",
      "label": "EN 407 Heat protection",
      "selected_combination_mode": "and",
      "available_combination_mode": "and",
      "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg"
    },
    "values": [
      {
        "key": "en407-flame",
        "label": "burning behaviour",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a390b5.jpg",
        "is_selected": true,
        "product_count": 450
      },
      {
        "key": "en407-contact",
        "label": "contact heat resistance",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a39585.jpg",
        "is_selected": true,
        "product_count": 55
      },
      {
        "key": "en407-convective",
        "label": "convective heat",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a39585.jpg",
        "is_selected": false,
        "product_count": 104
      },
      {
        "key": "en407-radiant",
        "label": "radiant heat resistance",
        "picto_url": "https://app.ppe-analytics.com/static/pictos/300/fc6d75d7-8366-424e-b526-4bc333a39585.jpg",
        "is_selected": false,
        "product_count": 45
      }
    ]
  }
}
Response example (200 - submit filter choices)
{
  "status": "OK",
  "result": {
    "context": {
      "locale": "en",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "product_count": 550,
      "api_follow_guide": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/follow",
      "api_guide_results": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/results"
    }
  }
}

Check API status

GET /status

Checks the status of the API, with a basic request to the database behind the scenes to ensure that the API is really available.

Responses
GET /status
curl \
 -X GET https://api.ppe-analytics.com/api/v1/status
Response example (200)
{
  "status": "OK",
  "message": "Welcome to Deck API! Check out the API doc at https://api-doc.ppe-analytics.com"
}
Response example (503)
{
  "status": "ERROR",
  "message": "Deck API is temporarily unavailable. We're working on it to bring it back as soon as possible."
}

Check API key

GET /connect

Checks if the provided API key is valid.

Responses
GET /connect
curl \
 -X GET https://api.ppe-analytics.com/api/v1/connect \
 -H "PPEApiKey: $API_KEY"
Response example (200)
{
  "status": "OK",
  "message": "This API key is valid for coporation mi-6"
}
Response example (403)
{
  "status": "ERROR",
  "message": "Invalid API key. Did you provide it as PPEAPIKey header? Check the doc at https://api-doc.ppe-analytics.com. Contact us at support@ppe-analytics.com if you need some help."
}