Export Data In Tabular Format

Use the API to export data in a tabular format as CSV, XLSX, PDF and HTML files:

  1. Decide if you want to export an existing visualization or a custom report:

    • To export a visualization, you need to get the visualization’s ID. Note that visualizations can only be exported as PDF or HTML files using this method.
    • To export a custom report, you need to get the report’s execution result ID. See Access Raw Data Through API to learn how to create custom reports.

  2. Create a tabular export

  3. Download the tabular export

Create a Tabular Export

Create a tabular export by making a POST call to the API endpoint api/v1/actions/workspaces/<workspace_id>/export/tabular.

In the body of the request, specify the format of the tabular export, the export’s file name and the ID of your visualization or custom report you are exporting:

curl $HOST_URL/api/v1/actions/workspaces/<workspace_id>/export/tabular \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "format": "<CSV|XLSX|PDF|HTML>",
    "fileName": "<tabular_export_file_name>",
    "<executionResult|visualizationObject>": "<execution_result_id|visualizationObjectId>"
}
'

Note that for a visualizationObject only the PDF or HTML formats are supported.

Example: Create a CSV tabular export from a custom report:

curl $HOST_URL/api/v1/actions/workspaces/914717b587f94f6c856e6a1a06fd7315/export/tabular \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "format": "CSV",
    "fileName": "revenue_per_country",
    "executionResult": "69268c79371ce9e2940c9de92e3025bb03c62b7f"
}
'

Note that if you are using the PDF or HTML formats, you can define additional configuration options.

After making a successful tabular export request, you will get back an export result ID:

{
    "exportResult": "<export_result_id>"
}

You will need the <export_result_id> value to retrieve the tabular export.

Download a Tabular Export

Once you have created a tabular export and have its <export_result_id>, you can retrieve it by making a GET call to the API endpoint api/v1/actions/workspaces/<workspace_id>/export/tabular/<export_result_id>:

curl $HOST_URL/api/v1/actions/workspaces/<workspace_id>/export/tabular/<export_result_id> \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-X GET

You will get your tabular export, for example in case of a CSV tabular export you may get something like:

"a_date.year","2020","2021","2022","2023","2024"
"a_products.category","m_revenue","m_revenue","m_revenue","m_revenue","m_revenue"
"Clothing",4289.33,14424.44,18354.85,25366.38,32028.27
"Electronics",3215.41,17915.25,17935.01,21806.1,29413.16
"Home",2095.55,11496.5,13219.1,19083.86,23204.74
"Outdoor",14402.34,41925.55,25103.18,65494.44,62641.47

PDF and HTML Configuration Options

When calling the API endpoint api/v1/actions/workspaces/<workspace_id>/export/tabular you can define additional settings for how the PDF or HTML export should look like.

The fields format, executionResult or visualizationObject and filename are mandatory.

{
    "format" : "PDF",
    "executionResult" : "<execution_result_id>",
    "filename" : "<file_name>",
    "visualizationObjectCustomFilters" : [ <custom_IFilter_definitions> ],
    "settings" : {
        "showFilters" : "true",
        "pdfPageSize" : "a4 landscape",
        "pdfTopLeftContent" : "TOP LEFT TEXT",
        "pdfTopRightContent" : "TOP RIGHT TEXT",
        "pdfTableStyle" : [
            {
                "selector" : "td",
                "properties" : [
                    {
                    "key" : "font-size",
                    "value" : "15px"
                    }
                ]
            }
        ]
    }
}

The optional fields are:

  • visualizationObjectCustomFilters - Override filters when using visualizationObject. See IFilter definition.

  • showFilters: true|false - Print applied filters on top of the document. Supported for HTML. Supported for PDF only when using when visualizationObject.

  • pdfPageSize: a4 portrait - Page size and orientation. Accepts any of the @page/size arguments listed here. Supported for PDF only.

  • pdfTopLeftContent and pdfTopRightContent - Custom content in the top-left and top-right header of every PDF page. Supported for PDF only. Note that the bottom-left footer content is reserved for datetime of the export; and the bottom-right footer content is reserved for the page info.

  • pdfTableStyle - Custom CSS styles for the table.

Export Definitions

Export definitions are templates for tabular export configuration options. Stored in GoodData, these templates can be reused by anyone to consistently export visualizations with the same settings each time.

To create an export definition, make a POST call to the API endpoint api/v1/entities/workspaces/<workspace_id>/exportDefinitions:

curl $HOST_URL/api/v1/entities/workspaces/<workspace_id>/exportDefinitions \
-H 'Authorization: Bearer $API_TOKEN' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "type": "exportDefinition",
    "id": "<your_custom_export_definition_id>",
    "attributes": {
    "title": "<name_your_export_definition>",
    "description": "<describe_your_export_definition>",
    "tags": [
        "<optional_tag>",
        "<optional_tag_2>"
    ],
    
    "requestPayload": {
        <CONFIGURATION_OPTIONS>
    },

    "areRelationsValid": true
    },
    "relationships": {
    "visualizationObject": {
        "data": {
        "id": "string",
        "type": "visualizationObject"
        }
    }
    }
}
'

where <CONFIGURATION_OPTIONS> is the JSON payload described in PDF and HTML Configuration Options.

You can then use the GET API endpoint api/v1/entities/workspaces/<workspace_id>/exportDefinitions/<export_definition_id> to retrieve the export definition and use it as a payload when calling the API endpoint api/v1/actions/workspaces/<workspace_id>/export/tabular.

Ideally you may want to automate the process using our Python SDK. For instance you can create tabular exports using the Python script shown in this example.

Troubleshooting

Make note of the following:

  • When attempting to export tables to PDF, you might encounter an HTTP 404 error if the dataset exceeds the current export capacity. Our PDF exporter is optimized for handling datasets up to approximately 6,000 cells.

  • If your requirement involves exporting larger datasets to PDF, please reach out to our support team for assistance.

  • Should you face an HTTP 404 error during PDF export, it’s worth noting that exporting the data to HTML remains a viable alternative.

Access Raw Data
API Reference