Skip to main content

$format

Functionality​

Definition​

The $format endpoint allows you to specify the format in which data from a dataclass should be returned. This parameter is essential for integrating with different systems that require data in specific formats, such as JSON or Looker Studio.

Syntax​

To use the $format parameter, append it to your GET request in the following manner:

GET /rest/{{dataClass}}?$format={{format}}

Supported Formats​

The following formats are supported by the $format parameter:

FormatDescription
jsonStandard REST server format (used by default)
lookerJSON format compliant with Looker Studio
tip

  • When using the json format, the data is returned in a simple, flat JSON structure. This is the default format if $format is not specified. It is ideal for most general-purpose applications and integrations.

  • When using the looker format, the data is structured to be compliant with Looker Studio's requirements. It includes additional metadata such as schema definitions and semantic information. This format is particularly useful for visualizing data in Looker Studio.

Combining with Other Parameters​

The $format parameter can be combined with other parameters to customize and refine data retrieval and presentation:

  • $filter: Apply filters to the data before formatting the response.

  • $orderby: Sort the data before applying the format.

  • $top/$limit and $skip: Limit the number of records and skip a certain number of records before formatting.

  • $expand: Include related data in the formatted response.

  • $attributes: Specify which attributes to include in the formatted response.

  • $compute: Perform calculations on the data before formatting the response.

  • $distinct: Retrieve distinct values from the data and format the response accordingly.

  • $method=entityset: Create an entity set and format the response based on the specified format.

Use Cases​

Using the Default JSON Format​

If you do not specify the $format parameter, the data is returned in the standard JSON format by default.

Request:

GET /rest/Company

Response:

[
    {
        "ID": 1,
        "name": "Alpha Astral Animations",
        "address": "Ullman Drive (82)"
    },
    {
        "ID": 2,
        "name": "Alpha Bart Computing",
        "address": "Lehigh Square (110)"
    },
    {
        "ID": 3,
        "name": "Alpha Business Clock-making",
        "address": "Larchmont Terrace (90)"
    }
]

Using the Looker Format​

To retrieve data in a format compliant with Looker Studio:

Request:

GET /rest/Company?$filter="name begin a"&$top=3&$format=looker

Response:

{
    "schema": [
        {
            "name": "ID",
            "dataType": "NUMBER",
            "semantics": {
                "conceptType": "METRIC",
                "semanticGroup": "NUMERIC",
                "semanticType": "NUMBER"
            }
        },
        {
            "name": "Name",
            "dataType": "STRING",
            "semantics": {
                "conceptType": "DIMENSION",
                "semanticGroup": "TEXT",
                "semanticType": "TEXT"
            }
        },
        {
            "name": "Email",
            "dataType": "STRING",
            "semantics": {
                "conceptType": "DIMENSION",
                "semanticGroup": "TEXT",
                "semanticType": "TEXT"
            }
        }
    ],
    "rows": [
        {
            "values": [
                10,
                "Harry",
                "user10@example.com"
            ]
        },
        {
            "values": [
                9,
                "test",
                "user9@example.com"
            ]
        },
        {
            "values": [
                8,
                "user8",
                "user8@example.com"
            ]
        }
    ],
    "filtersApplied": false,
    "__COUNT": 10,
    "__FIRST": 0
}