We're updating our knowledge graph! All services are available, but you may observe increased latency.

API Documentation

The Cobaltmetrics API gives you programmatic access to the data and the algorithms used in Cobaltmetrics.

Authentication

Authentication is necessary to monitor usage and assist users with any errors that may occur.

HTTP Authorization

By default, Cobaltmetrics uses API keys to identify users and their privileges. To create an API key, see the developer tools page. To use your API key, use the Authorization HTTP header. In the example requests below, substitute YOUR_API_KEY in the code snippets with the API key you got from the developer tools page.

API keys must be saved locally before you navigate to another page or log out of Cobaltmetrics. To save a new API key, click the clipboard icon to copy the key to your clipboard, and store it securely on your device. If you lose access to any of your API keys, you must delete it and create a new one.

API keys do not expire, and each user can create up to 5 keys.

IP Address Authentication

If requests are sent to the API without the Authorization HTTP header, then the IP address of the client or last proxy that sent the request is used to monitor usage. There are very strict quotas and throttles for users who are not authenticated, and it is not recommended to use the API without authenticating.

Quotas and limits

We put limits and quotas on all requests to protect Cobaltmetrics from receiving more data than it can handle, and to ensure an equitable distribution of our resources.

All requests count against your quotas, whether you use the web application or the REST API, except requests sent to api/v2/quotas. The limits and quotas are subject to change, and we also reserve the right to temporarily limit API usage without warning when we see a pattern of requests causing the API to be unusable for most users.

Quotas

We combine two types of quotas:

  • The number of requests you can send every minute;
  • The total number of requests you can send every day.

Unauthenticated users have lower quotas than authenticated users:

  • Unauthenticated users can send up to 30 requests per minute, and a total of 100 requests per day;
  • Authenticated users can send up to 60 requests per minute, and a total of 1,000 requests per day.

We will soon introduce a small number of plans with different quotas and privileges. Please contact us if you are interested.

HTTP headers

To monitor your usage, you can use the HTTP headers of any response sent by the API.

Per-minute quotas

By default, the following HTTP headers will be returned with each response:

  • X-PerMinute-RateLimit-Limit: the per-minute rate limit ceiling;
  • X-PerMinute-RateLimit-Remaining: the number of requests left for the current time window.

If you exceed the rate limit, the API will return a HTTP 429 "Too Many Requests" response code and the following HTTP headers will be added to the response:

  • Retry-After: how long you should wait before making another request;
  • X-PerMinute-RateLimit-Reset: the remaining window before the rate limit resets.

Daily quotas

By default, the following HTTP headers will be returned with each response:

  • X-RateLimit-Limit: the daily rate limit ceiling for your current plan;
  • X-RateLimit-Remaining: the number of requests left for the current time window.

If you exceed the rate limit, the API will return a HTTP 429 "Too Many Requests" response code and the following HTTP headers will be added to the response:

  • Retry-After: how long you should wait before making another request;
  • X-RateLimit-Reset: the remaining window before the rate limit resets.

Unstable operations

Because we aggregate data from different sources, there are many moving parts in the API, and reproducibility is a challenge. Our default strategy is to ingest the entire datasets into Cobaltmetrics, so that we control when and how data gets updated.

Some operations, however, interact with third-party services and thus cannot be guaranteed to return the same results over time. Caching results is not always an option, as we would risk returning stale data. We refer to these operations as unstable operations.

All unstable operations are disabled by default and need to be explicitely enabled by using the X-Release HTTP header in the requests you send to the API:

  • X-Release: stable: this is the default setting, whereby unstable operations are disabled;
  • X-Release: unstable: this is the setting whereby all operations are enabled, stable operations and unstable operations alike.

The following unstable operations are currently available in the API:

  • HTTP Link header interpolation, see the page on URI transmutation for more information.

Note that unstable operations are currently unavailble in the web application, they can only be enabled via REST requests.

v1

The first version of the API was deprecated in December 2018 and removed in April 2019. Requests sent to v1 endpoints will now trigger HTTP 410 "Gone" responses.

v2

Citations

This endpoint allows you to execute a search query and get back all the information that is displayed on a URI page with a single request: parsed query, citations, citation count, URI badges, and facets. Our web application runs on this endpoint.

HTTP request

GET api/v2/search

Query parameters

ParameterTypeStatusDescription
query String Required The query string, see our page on search queries for more information
autolink Boolean Optional Whether the URI transmutation API should be used to collate citations to URIs known to be equivalent to URIs in the query string
page Integer Optional The page number, to navigate through pagination if there are many results
badges Boolean Optional Whether badges should be included in the response
facets Boolean Optional Whether facets should be included in the response

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/search?query=domain:wikipedia.org" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/search?query=domain:wikipedia.org",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "badges": [],
    "citation-count": 1261,
    "citations": [],
    "facets": [],
    "query": {
        "autolink": true,
        "input": "domain:wikipedia.org",
        "tokens": [
            {
                "status": "valid",
                "token": "domain:wikipedia.org",
                "type": "term",
                "value": {
                    "equivalent-uris": [
                        "domain:wikipedia.org"
                    ],
                    "interpolations": [
                        "host:wikipedia.org",
                        "host:www.wikipedia.org",
                        "http://wikipedia.org/",
                        "http://www.wikipedia.org/",
                        "https://wikipedia.org/",
                        "https://www.wikipedia.org/"
                    ],
                    "normal-form": "domain:wikipedia.org"
                }
            }
        ]
    }
}

Get citations

This endpoint allows you to execute a search query on our citation index and get back all citations that match the query.

HTTP request

GET api/v2/citations

Query parameters

ParameterTypeStatusDescription
query String Required The query string, see our page on search queries for more information
autolink Boolean Optional Whether the URI transmutation API should be used to collate citations to URIs known to be equivalent to URIs in the query string
page Integer Optional The page number, to navigate through pagination if there are many results

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/citations?query=domain:wikipedia.org" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/citations?query=domain:wikipedia.org",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

[
    {
        "date": 1543388047693,
        "date-precision": "NANOS",
        "matching-uris": [
            "domain:wikipedia.org"
        ],
        "source-dataset": "hypothesis",
        "source-dataset-name": "Hypothesis",
        "source-domain": "hypothes.is",
        "source-host": "hypothes.is",
        "title": "Annotation on https://en.wikipedia.org/wiki/Neutronium",
        "url": "https://hypothes.is/a/Zt_OnPLaEeiyvRdeSne2Ag"
    },
    {
        "date": 1543359032288,
        "date-precision": "NANOS",
        "matching-uris": [
            "domain:wikipedia.org"
        ],
        "source-dataset": "hypothesis",
        "source-dataset-name": "Hypothesis",
        "source-domain": "hypothes.is",
        "source-host": "hypothes.is",
        "title": "Annotation on https://en.wikipedia.org/wiki/Song_of_Solomon_(novel)",
        "url": "https://hypothes.is/a/2FisBPKWEeig7ZsIFuIsvw"
    }
]

Get citation counts

This endpoint allows you to execute a search query on our citation index and get back the number of citations that match the query.

HTTP request

GET api/v2/citations/count

Query parameters

ParameterTypeStatusDescription
query String Required The query string, see our page on search queries for more information
autolink Boolean Optional Whether the URI transmutation API should be used to collate citations to URIs known to be equivalent to URIs in the query string

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/citations/count?query=domain:wikipedia.org" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/citations/count?query=domain:wikipedia.org",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

1261

Get URI badges

Badges are simple indicators that summarize what we know about a given URI. See our page on URI badges for more information.

HTTP request

GET api/v2/uri/badges

Query parameters

ParameterTypeStatusDescription
uri String Required URI to get badges for
type[] String Optional Any combination of alerts, citations, digests, equivalent-uris, resolver-urls, and/or short-urls
values Boolean Optional Whether badge values should be included in the response, or only counts

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/uri/badges?uri=rfc:3986" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/badges?uri=rfc:3986",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "badges": {
        "alerts": {
            "count": 0
        },
        "citations": {
            "count": 124
        },
        "digests": {
            "count": 0
        },
        "equivalent-uris": {
            "count": 1
        }
    },
    "link": "https://cobaltmetrics.com/uri/rfc%3A3986",
    "uri": "rfc:3986"
}

Statistics

Get global statistics

This endpoint returns global statistics for various entities indexed by Cobaltmetrics: documents, citations, and identifiers.

HTTP request

GET api/v2/statistics

Query parameters

None.

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/statistics" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/statistics",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "citations": {
        "total": 291756,
        "items": []
    },
    "documents": {
        "total": 384475,
        "items": []
    },
    "identifiers_counts": {
        "items": {
            "http": 1309,
            "https": 1058
        },
        "total": 2369
    },
    "knowledge_base_triples": {
        "items": {
            "other": 79865,
            "short_urls": 380000
        },
        "total": 459865
    }
}

URI Transmutation

Normalize a URI

For all URI schemes, we apply normalization operations that preserve semantics per section 6 of RFC 3986, including, when applicable, converting the scheme and host to lower case and removing the default port. For some URI schemes, we use additional scheme-specific rules to further normalize the input URI according to the specification of each scheme and type of identifier. Given that URI normalization is scheme-dependent, relative URIs (i.e. URIs that do not specify a scheme) cannot be normalized and will thus be rejected by this API. See our page on URI transmutation for more information.

HTTP request

GET api/v2/uri/normal-form

Query parameters

ParameterTypeStatusDescription
uri String Required URI to be normalized

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/uri/normal-form?uri=bcp:4" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/normal-form?uri=bcp:4",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "input": "bcp:4",
    "output": "bcp:0004"
}

Get equivalent URIs

Return all URIs known to be equivalent to the input URI, including the (normalized) input itself. The optional and repeatable parameter scheme is used to control the possible schemes of the output URIs. By default, when scheme is not used, all schemes supported in Cobaltmetrics will be returned. If scheme is used, only URIs with one of specified schemes will be returned. See our page on URI transmutation for more information.

HTTP request

GET api/v2/uri/equivalent-uris

Query parameters

ParameterTypeStatusDescription
uri String Required URI to be transmuted
scheme[] String Optional Any combination of URI schemes supported by Cobaltmetrics, see our page on URI schemes for the complete list

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/uri/equivalent-uris?uri=bcp:4" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/equivalent-uris?uri=bcp:4",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "input": "bcp:4",
    "output": [
        "bcp:0004",
        "doi:10.17487/RFC1917",
        "https://doi.org/10.17487/RFC1917",
        "rfc:1917"
    ]
}

Get equivalent URLs

Return all URLs known to be equivalent to the input URI, including, when applicable, the (normalized) input itself. In this context, URLs are defined as absolute URIs whose scheme is http, https, or ftp. Note that calling api/v2/uri/equivalent-urls?uri=xxx:yyy is equivalent to calling api/v2/uri/equivalent-uris?uri=xxx:yyy&scheme=ftp&scheme=http&scheme=https. See our page on URI transmutation for more information.

HTTP request

GET api/v2/uri/equivalent-urls

Query parameters

ParameterTypeStatusDescription
uri String Required URI to be transmuted

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/uri/equivalent-urls?uri=bcp:4" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/equivalent-urls?uri=bcp:4",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "input": "bcp:4",
    "output": [
        "https://doi.org/10.17487/RFC1917"
    ]
}

Interpolate a URI

Interpolations are a special class of URI equivalence rules that do not hold in all cases, but they hold in most cases and the impact of false positives is minimal. See our page on URI transmutation for more information.

HTTP request

GET api/v2/uri/interpolations

Query parameters

ParameterTypeStatusDescription
uri String Required URI to be interpolated

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/uri/interpolations?uri=https://cobaltmetrics.com/" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/interpolations?uri=https://cobaltmetrics.com/",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{}

Quotas

Check your quotas

This endpoint allows you to check your quotas. Information about your quotas will be returned in the HTTP headers if you send your request with the HEAD method, and in both the HTTP headers and the HTTP message body if you send your request with the GET method. Requests sent to this endpoint do not count against your quotas.

HTTP request

GET api/v2/quotas

Query parameters

None.

Example requests

    
curl -X GET "https://cobaltmetrics.com/api/v2/quotas" \
    -H "Authorization: YOUR_API_KEY"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/quotas",
    "method": "GET",
        "headers": {
                "Authorization": "YOUR_API_KEY",
                }
    }

    $.ajax(settings).done(function (response) {
    console.log(response);
});
    

Example response

{
    "per-minute-rate-limiting": {
        "limit": 60,
        "remaining": 60,
        "retry-after": 0,
        "available-at": {
            "date": "2018-09-06 15:21:14.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    },
    "rate-limiting": {
        "limit": 1000,
        "remaining": 1000,
        "retry-after": 0,
        "available-at": {
            "date": "2018-09-06 15:21:14.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        }
    }
}