Visualize API responses

Postman provides a programmable way to visually represent your request responses. Visualization code added to the Tests for a request will render in the Visualize tab for the response body, alongside the Pretty, Raw, and Preview options.

Visualizer bar chart rendering

Visualizers let you present your response data in ways that help to make sense of it. You can use visualizers to model and highlight the information that's relevant to your project, instead of having to read through raw response data. When you share a Postman collection, other people on your team can also see your visualizations within the context of each request.

Contents

Visualizing response data

To visualize your response data, add code to the Pre-request or Tests script for the request. The pm.visualizer.set() method will apply your visualizer code to the data and present it in the Visualize tab when the request runs.

Adding visualizer code

The pm.visualizer.set() method accepts a Handlebars template string as its first parameter. The second parameter should be the data you want to use the template to display. Read on to learn how you can build a Handlebars template and pass data to it.

Rendering HTML

To see a basic visualizer in action, open the following request in Postman:

Run in Postman

The example endpoint responds with a list of names and email addresses with the following JSON response body structure:

[
    {
        "name": "Alice",
        "email": "alice@example.com"
    },
    {
        "name": "Jack",
        "email": "jack@example.com"
    },
    // ... and so on
]

The visualizer code creates a Handlebars template to render a table displaying the names and email addresses by looping over an array. Handlebars can do this with the {{#each}} tag. This script runs in the request Tests:

var template = `
    <table>
        <tr>
            <th>Name</th>
            <th>Email</th>
        </tr>

        {{#each response}}
            <tr>
                <td>{{name}}</td>
                <td>{{email}}</td>
            </tr>
        {{/each}}
    </table>
`;

The variable names inside the double curly braces in the template will be substituted by the data passed to the pm.visualizer.set() method. To apply the template, the following code completes the Tests script:

// Set visualizer
pm.visualizer.set(template, {
    // Pass the response body parsed as JSON as `data`
    response: pm.response.json()
});

The template variable is the template string created earlier. The second argument passed is an object defined as the response property—this is the variable that the template expects in the {{#each response}} loop. The value assigned to the response property is the response JSON data from the request parsed as an object.

Viewing visualizations

Send the request in Postman and select the Visualize tab to see the table.

Visualizer table rendering

The table is rendered as HTML as it would be in a web browser.

Adding styling and interaction to visualizations

You can load an external stylesheet using <link> tags in your HTML template code, using the same technique as adding a stylesheet to a web page. You can also add stylesheets as <style> tags. Similarly, you can add interactions using JavaScript code in <script> tags inside your template HTML code.

Using your own libraries

You can use any of the libraries in the Postman Sandbox to programmatically generate the layout template. To import an additional external JavaScript library, add the URL to a <script> tag in the template code, using the same approach you would use to load JavaScript into an HTML file. This lets you render your request data using the visualization tool of your choice (for example D3.js).

Accessing data inside the template

Any <script> elements inside your template can access the data passed in the second argument to pm.visualizer.set() by calling the pm.getData(callback) method. This is only applicable to JavaScript code in the template, for example if your template includes code to render a chart.

The pm.getData(callback) method takes a callback function as its parameter. This callback accepts two parameters: error and data. The second parameter is the data that was passed to pm.visualizer.set().

Try it out

See more visualizer code working by importing any of the following collections. Use the Run in Postman buttons to import from the documentation for each one. Import the collection > open a request from Collections on the left sidebar in Postman > click Send to run it—you'll see the rendered data in Visualize.

Visualizer API

You can access visualizers from the Postman API. The pm.visualizer.set() method takes three parameters:

  • layout (required): The first parameter is a Handlebars HTML template string.
  • data (optional): The second parameter is data that you can bind to the template. The properties of this object can be accessed in the template.
  • options (optional): The third argument is an options object for Handlebars.compile(). You can use this to control how Handlebars compiles the template.

Postman uses the information you pass to pm.visualizer.set() to render an HTML page in the sandbox for the visualizer. You will see this rendered HTML page in the Visualize tab. The layout string is inserted into the <body> of the rendered page, including any JavaScript, CSS, and HTML that the template contains.

Debugging visualizers

You can debug a visualization in Postman by right-clicking in the Visualize area and choosing Inspect visualization. This will open the visualizer Developer Tools attached to the sandbox. You can use it in the same way as debugging a web page.

Debugging Visualizers in Postman

Next steps

The visualizer demo video walks through the process of building visualizations in Postman.

You can try experimenting with visualizations using the collections listed above as a starting point and tweak the code to get the results you need for your own data. For more on how Postman provides access to your response data inside scripts, check out the Test Examples.