Skip to content
Grid Reporting API
/
Grid API Intro
Last updated

Grid Reporting API

ObservePoint's Grid Reporting API gives developers access to all of ObservePoint's data about your websites.

What is the Grid API?

The ObservePoint Grid API lets developers get all the data that powers ObservePoint reports. It's called the "Grid" API because it returns rows and columns.

The Grid API lets you filter, sort, group, and paginate the data you want.

It provides this data as a dense JSON array and lets you export the data as CSV, TSV, Excel, and Parquet.

How do I use the Grid API?

Authentication

The Grid API uses the same authentication as the rest of the ObservePoint API. For details, see authentication.

Getting Data

Make a POST request to the Grid API containing JSON that describes the data you want.

To build your request:

  1. Choose the entity type to query
  2. Choose columns
  3. Apply filters (optional)
  4. Choose sort order (optional)
  5. Choose pagination (optional)
  6. Choose grouping (optional)

Once you've chosen the above, get the data by sending a POST request to the entity's endpoint.

Include these headers:

  • Authorization: api_key <your-api-key-goes-here>
  • Content-Type: application/json

Send the following JSON in the request body:

The JSON may seem big, but that's because it's expressive and powerful!

Example POST to https://api.observepoint.com/v3/reports/grid/<entity-type>
{ 
  // Specify the columns you want in this array:
  "columns": [
    { 
      "columnId": "EXAMPLE_COLUMN_ID"
    },
    {
      "columnId": "ANOTHER_EXAMPLE_COLUMN_ID"
    }
    // Add more column IDs here if you want
  ],
  "sortBy": [
    {
      "columnIndex": 0, // 0-based column index in the `columns` array above
      "sortDesc": false
    },
    // (optional) Sort by a 2nd column to break ties in the 1st sort column
    //{
    //  "columnIndex": 2,
    //  "sortDesc": true
    //}
  ],
  // Specify your filters here (optional):
  "filters": {
    "conditionsMatchMode": "all", // if you have more than 1 filter, specify "all" or "any"
    "conditions": [
      {
        "operator": "string_contains", // see the filters doc for supported operators
        "arg": "example string to filter by",
        "filteredColumn": {
          "columnId": "EXAMPLE_COLUMN_ID" // the column on which to apply the filter
        }
      }
    ]
  },
  // Pagination (optional):
  "page": 0,  // 0-based pagination
  "size": 10000 // number of rows to return, max 10,000
}

Getting Results

The response is JSON that includes the rows that match your request.

To save space, the Grid API returns the data as a 2-dimensional array of arrays, where each array represents one row.

Sample results
{
  "metadata": {
    // For convenience, this is the list of columns you requested,
    // in the order you requested them
    "headers": [
      {"column": {"columnId": "EXAMPLE_COLUMN_ID"}},
      {"column": {"columnId": "ANOTHER_EXAMPLE_COLUMN_ID"}}
    ],
    // The pagination tells you if there are more rows to request
    "pagination": {
      "totalCount": 42000,
      "totalPageCount": 5,
      "pageSize": 10000,
      "currentPageSize": 10000,
      "currentPageNumber": 0
    },
  },
  // The actual data is encoded as a dense array to save space:
  "rows": [
    ["Example Value 1", "https://example.com/value1"],
    ["Example Value 2", "https://example.com/value2"]
    // 9,998 more rows here
  ]
}
Previous page
Next page