This API documentation comes to replace Botify's previous documentation. This revamp comes with a paradigm shift around the way SEO data is retrieved using Botify's API.

The present documentation introduces what is referred to as BQLv2 (see BQL Introduction) with comparison to BQLv1 presented in the previous documentation.

The past concepts behind BQLv1

At the time of writing, BQLv1 is still in-use but its design limits its capabilities.
The core concept of BQLv1 is to query crawl-centered data. One can query SEO data linked to a SiteCrawler analysis, potentially compare it another crawl.
When data is not available for a crawl, it cannot be queried.

BQLv1 defines multiple API endpoints to be queried:

• to list URLs, /v1/analyses/<USERNAME>/<PROJECT_SLUG>/<ANALYSIS_SLUG>/urls using a syntax like:

{
  "fields": [
    "url",
    "depth",
    "http_code"
  ],
  "filters": {
    "field": "indexable.is_indexable",
    "predicate": "eq",
    "value": true
  }
}

• to aggregate data /v1/analyses/<USERNAME>/<PROJECT_SLUG>/<ANALYSIS_SLUG>/urls/aggs with a syntax like:

[
  {
    "aggs": [
      {
        "metrics": [
          "count"
        ]
      }
    ],
    "filters": {
      "field": "indexable.is_indexable",
      "value": true
    }
  }
]

A new era BQLv2

The concept behind BQLv2 is to query SEO data at a project-level. Which means that any available source of data (called collections) can be queried and crossed with another collection.
As explained thoroughly in the hereby documentation, only one API endpoint is necessary to express any retrieval use case. This is done in a syntax like:

{
  "collections": [
    "crawl.20200101"
  ],
  "query": {
    "dimensions": [
      "crawl.20200101.indexable.is_indexable"
    ],
    "metrics": [
      "crawl.20200101.count_urls_crawl"
    ]
  }
}