Access Raw Data Through API

Use the AFM (Attributes, Filters, Metrics) API if you want to get data from your GoodData and do not want to use Dashboards, Analytics Designer, or GoodData.UI (these applications get data automatically in the background).

A simple scenario to get data uses the following two endpoints:

Retrieve Data by API

To retrieve data, you need to call the two endpoints mentioned above. The execute endpoint computes the result based on the AFM body. The result endpoint returns data based on resultId.

AFM diagram

Understand the Concept

The key concept is the AFM (Attributes, Filters, Metrics):

  • An attribute breaks the metric apart and provides context to the data.
  • A filter is a set of conditions that removes specific values from your original data.
  • A metric is a computational expression that aggregates one or more numerical values.

These are best described with an example. Imagine you are an account manager for an e-commerce shop. You want to know the number of orders in states that are in the ‘West’ region. Let’s display your data as a column chart:

Introductory column chart

Compute

To compute the result, you need to call the execute endpoint with the following body; in the body, you specify which attributes, filters, and metrics have to be used in the computation:

{
  "resultSpec":{
    "dimensions":[
      {
        "localIdentifier":"dim_0",
        "itemIdentifiers":["measureGroup"]
      },
      {
        "localIdentifier":"dim_1",
        "itemIdentifiers":["a_state"],
        "sorting":[
          {
            "attribute":{
              "attributeIdentifier":"a_state",
              "sortType":"DEFAULT"
            }
          }
        ]
      }
    ],
    "totals":[]
  },
  "execution":{
    "measures":[
      {
        "localIdentifier":"m_quantity_sum",
        "definition":{
          "measure":{
            "item":{
              "identifier":{
                "id":"quantity",
                "type":"fact"
              }
            },
            "aggregation":"SUM"
          }
        }
      }
    ],
    "attributes":[
      {
        "label":{
          "identifier":{
            "id":"state",
            "type":"label"
          }
        },
        "localIdentifier":"a_state"
      }
    ],
    "filters":[
      {
        "negativeAttributeFilter":{
          "label":{
            "identifier":{
              "id":"region",
              "type":"label"
            }
          },
          "notIn":{
            "values":[
              "Unknown",
              "Northeast",
              "Midwest",
              "South"
            ]
          }
        }
      }
    ],
    "auxMeasures":[]
  },
  "settings":{}
}
  • dimensions - communicate to the backend how to organize data. In this example, we have set in the body that all measureGroup metrics will be in the dim_0 dimension and the a_state attribute in the dim_1 dimension.

Get Result

Once you get a response from the execute endpoint, you will be given a resultId:

{
   "executionResponse":{
      "dimensions":[...],
      "links":{
         "executionResult":"<resultId>"
      }
   }
}

You can then call the result endpoint using the resultId to retrieve the computed data:

{
   "data":[
      [27.0, 89.0, 391.0, 55.0, 27.0, 8.0, 19.0, 20.0, 20.0, 32.0, 36.0, 44.0]
   ],
   "dimensionHeaders":[
      {
         "headerGroups":[
            {
               "headers":[
                  {
                     "measureHeader":{
                        "measureIndex":0
                     }
                  }
               ]
            }
         ]
      },
      {
         "headerGroups":[
            {
               "headers":[
                  {
                     "attributeHeader":{
                        "labelValue":"AK",
                        "primaryLabelValue":"AK"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Arizona",
                        "primaryLabelValue":"Arizona"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"California",
                        "primaryLabelValue":"California"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Colorado",
                        "primaryLabelValue":"Colorado"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Hawaii",
                        "primaryLabelValue":"Hawaii"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Idaho",
                        "primaryLabelValue":"Idaho"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Montana",
                        "primaryLabelValue":"Montana"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Nevada",
                        "primaryLabelValue":"Nevada"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"New Mexico",
                        "primaryLabelValue":"New Mexico"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Oregon",
                        "primaryLabelValue":"Oregon"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Utah",
                        "primaryLabelValue":"Utah"
                     }
                  },
                  {
                     "attributeHeader":{
                        "labelValue":"Washington",
                        "primaryLabelValue":"Washington"
                     }
                  }
               ]
            }
         ]
      }
   ],
   "grandTotals":[],
   "paging":{
      "count":[1, 12],
      "offset":[0, 0],
      "total":[1, 12]
   }
}
  • data - the numerical points that you can display, for example, on the Y axis of a column chart.
  • headers - the text-based points that you can display, for example, on the X axis of a column chart or in a legend.

Next steps

If you do want to fetch data from GoodData, but you do not want to use an API, you can use both Python SDK or GoodData.UI as they provide you with a level of API abstraction.