What is the Power BI embedded analytics Client API?

Tip

To experiment with APIs in real time, using your own report or a sample report, visit the Power BI embedded analytics playground

The Power BI Client API is a client side library that allows you to programmatically control your embedded Power BI content, by using JavaScript or TypeScript.

Use the client APIs to communicate between Power BI items (such as reports and dashboards) and the application code. This gives you the flexibility to build an end user experience according to your design.

How does the Client library work?

The Client APIs communicate with an embedded Power BI item, such as a report or dashboard. The iframe creates a separation between the hosting app and the Power BI item, making sure the data is secured.

Diagram showing the Power BI JavaScript APIs in relation to Power BI.

  • Client application - The entire screenshot is an example of a client application.

  • Embedded report - The embedded report currently displayed in the application.

  • iFrame boundary - The embedded report is hosted inside an iFrame. The diagram outlines its boundary.

  • Client APIs - Use the Client APIs to communicate between the web application and the embedded component. For example, when calling report.setPage(…) the active page of the report will be changed. After the page is changed a pageChanged event will be emitted by the report, and you can add additional code in the event handler. For more information, see page navigation.

What does this documentation set include?

This documentation set lists the APIs for the following components:

  • powerbi-client - The main Power BI Client library which includes all the Power BI Client APIs except for powerbi-report-authoring. This library defines the classes for the different Power BI items that can be embedded. The powerbi-client library allows you to control the content you're embedding.

  • powerbi-models - Contains the object models for the Power BI Client APIs. For each model there is a TypeScript interface, a JSON schema definition, and a validation function to ensure a given object is a valid model.

  • powerbi-report-authoring - An extension for creating visuals and authoring the report after it's loaded. The powerbi-report-authoring library allows you to programmatically edit your embedded reports.

The documentation set also includes articles that explain how to use the APIs, alongside code examples. The articles are divided into the following sections:

  • Overview - Additional information about Power BI embedded analytics.

  • Playground showcases - Learn how to use embedded analytics in your apps quickly using the Power BI embedded analytics playground.

  • Start embedding - Learn how to embed each of the Power BI items such as reports and dashboards.

  • Basic concepts - Learn about some of the concepts every developer should be familiar with.

  • Report embedding - Additional embedding concepts applicable only for reports.

  • Report operations - Tweak your embedded report so that it provides a better user experience for your customers.

  • Embed reports for your organization - Create better embedded reports when embedding using the embed for your organization solution.

  • Report authoring - Articles dedicated to the powerbi-report-authoring APIs, allowing you to create and personalize visualizations after the report is loaded.

The Resources entry includes resources useful for Power BI developers.

Note

It's recommended to review these articles while experimenting with the Power BI embedded analytics playground.

Next steps