Botify Developer Portal

Find all information to automate your SEO workflow thanks to Botify's extensive data model.
You'll find comprehensive guides and documentation to help you start working.

The BQL differences

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"
    ]
  }
}

Updated about a month ago


What's Next

Discover how to migrate your BQLv1 queries to BQLv2

How to migrate from BQLv1 to BQLv2

The BQL differences


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.