================================
How to Unnest JSON Data in Excel
================================

A guide to working with JSON data returned from the **Dimensions Add-in for Excel**.

.. contents::
   :local:
   :depth: 2

---------------------
Installing the Add-in
---------------------

1. Open Microsoft Excel and start a new, blank workbook.

   .. image:: _static/images/excel_unnest_json/excel_unnest_01.png
      :alt: New blank workbook

2. In the **Home** ribbon, click **Add-ins** and search for **"Dimensions"**.
   Scroll until you see the Dimensions logo.

   .. image:: _static/images/excel_unnest_json/excel_unnest_02.png
      :alt: Add-ins menu showing Dimensions

3. Authenticate (or open the Add-in later from the **Data** ribbon).

4. Enter your **API key** and click **Login**.
   Keep **Endpoint** as default unless you have a reason to change it.

   .. image:: _static/images/excel_unnest_json/excel_unnest_03.png
      :alt: Authentication prompt for Dimensions Add-in

---------------
Running a Query
---------------

1. Select a target cell/sheet, type a query, and click **Run**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_04.png
      :alt: Running a query in the add-in

.. note::
   Before unnesting JSON columns, **save the workbook**.

----------------------
Unnesting JSON (macOS)
----------------------

1. **Data** ribbon → **Get Data** dropdown → **Get Data (Power Query)...**

   .. image:: _static/images/excel_unnest_json/excel_unnest_05.png
      :alt: Get Data menu on macOS

2. Choose **Excel workbook** as the data source.

   .. image:: _static/images/excel_unnest_json/excel_unnest_06.png
      :alt: Choose Excel workbook source (macOS)

3. Browse for the workbook you saved and click **Next**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_07.png
      :alt: Browse to saved workbook (macOS)

4. Preview loads → click **Transform Data**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_08.png
      :alt: Transform Data preview (macOS)

------------------------
Unnesting JSON (Windows)
------------------------

1. **Data** ribbon → **Get Data** dropdown → **Launch Power Query**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_09.png
      :alt: Launch Power Query on Windows

2. Choose **Excel workbook** as the data source.

   .. image:: _static/images/excel_unnest_json/excel_unnest_10.png
      :alt: Choose Excel workbook source (Windows)

3. Browse for the saved workbook, select **DSL Query** to preview, click **OK**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_11.png
      :alt: DSL Query preview (Windows)

----------------------
Working in Power Query
----------------------

1. In **Power Query Editor**, right-click the JSON column → **Change Type → Text**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_12.png
      :alt: Change column type to Text

2. With the column selected: **Transform** ribbon → **Parse → JSON**.

   .. image:: _static/images/excel_unnest_json/excel_unnest_13.png
      :alt: Parse JSON option

3. The column becomes a **[List]** (for arrays) or **[Record]** (for objects).
   Click the **Expand** (two diverging arrows) to give each list item its own row.

   .. image:: _static/images/excel_unnest_json/excel_unnest_14.png
      :alt: Expand list into rows

4. After expanding lists, you may see **Record** values.
   Click **Expand** again to split fields into columns.

   .. image:: _static/images/excel_unnest_json/excel_unnest_15.png
      :alt: Expand record into columns

.. tip::
   Check **Use original column name as prefix** to avoid name collisions.

5. Repeat expansions only where useful. Nested JSON can yield additional [List] or [Record] columns.

   .. image:: _static/images/excel_unnest_json/excel_unnest_16.png
      :alt: Additional nested expansions

------------
Close & Load
------------

When finished, click **Close & Load** (Home ribbon) to load the transformed data back into Excel.

.. image:: _static/images/excel_unnest_json/excel_unnest_17.png
   :alt: Close & Load

---------------------------------------
Full Walkthrough Screenshots (in order)
---------------------------------------

The following images continue the complete, sequential visual walkthrough. Use them as needed in your docs or replace any of the earlier screenshots if they match your UI better.

.. image:: _static/images/excel_unnest_json/excel_unnest_18.png
   :alt: Walkthrough 18

.. image:: _static/images/excel_unnest_json/excel_unnest_19.png
   :alt: Walkthrough 19

.. image:: _static/images/excel_unnest_json/excel_unnest_20.png
   :alt: Walkthrough 20

.. image:: _static/images/excel_unnest_json/excel_unnest_21.png
   :alt: Walkthrough 21

.. image:: _static/images/excel_unnest_json/excel_unnest_22.png
   :alt: Walkthrough 22

.. image:: _static/images/excel_unnest_json/excel_unnest_23.png
   :alt: Walkthrough 23

----------
Conclusion
----------

You’ve unpacked and normalized JSON data in Excel using Power Query.
The data is now ready for analysis with PivotTables and standard formulas.