Let us know which websites you would like to see included as a priority in future releases.
Please take our one-question survey, and share the link!

API Documentation

We are releasing version 2 of the API with new and improved endpoints. Version 1 will be supported until the end of December 2018.

v1

Statistics

Get global statistics

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

HTTP Request

GET api/v1/statistics/global

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/statistics/global" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/statistics/global",
    "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_cliques": {
        "items": {
            "other": 79865,
            "short_urls": 380000
        },
        "total": 459865
    }
}

Get a document statistics

This endpoint returns document(s) statistics based on a search token. Search tokens are generated using the "Generate a search token." feature. As of API version 2, this endpoint is deprecated. It is replaced by /api/v2/search, which returns the same information, but in a more normalized format and with more options. This endpoint will be removed on or after December 31, 2018.

HTTP Request

GET api/v1/document/facets/{token}

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/document/facets/{token}" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/document/facets/{token}",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

{
    "facets": {
        "citations_over_time": {
            "buckets": [
                {
                    "key_as_string": "07/2017",
                    "key": 1498867200000,
                    "doc_count": 1
                },
                {
                    "key_as_string": "08/2017",
                    "key": 1501545600000,
                    "doc_count": 7
                },
                {
                    "key_as_string": "09/2017",
                    "key": 1504224000000,
                    "doc_count": 4
                },
                {
                    "key_as_string": "10/2017",
                    "key": 1506816000000,
                    "doc_count": 3
                }
            ]
        }
    }
}

URIs, URLS, and identifiers

Normalize any 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.

HTTP Request

GET api/v1/uri/normal-form
Query Parameters
ParameterStatusDescription
uri required URI to be normalized

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/uri/normal-form?uri=bcp:4" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/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.

HTTP Request

GET api/v1/uri/equivalent-uris
Query Parameters
ParameterStatusDescription
uri required URI for which we want equivalent URIs
scheme[] optional http, https, or ftp

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/uri/equivalent-uris?uri=bcp:4&scheme[]=http&scheme[]=https&scheme[]=ftp" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/uri/equivalent-uris?uri=bcp:4&scheme[]=http&scheme[]=https&scheme[]=ftp",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

{
    "input": "bcp:4",
    "output": [
        "doi: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/v1/uri/equivalent-urls?uri=xxx:yyy is equivalent to calling api/v1/uri/equivalent-uris?uri=xxx:yyy&scheme=ftp&scheme=http&scheme=https.

HTTP Request

GET api/v1/uri/equivalent-urls
Query Parameters
ParameterStatusDescription
uri required URI for which we want equivalent URLs

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/uri/equivalent-urls?uri=bcp:4" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/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"
    ]
}

Get URI badges

Badges are simple indicators that summarize what we know about a given URI. See this page for more details.

HTTP Request

GET api/v1/uri/badges
Query Parameters
ParameterStatusDescription
uri required Get badges for this URI
type optional Specify badge types
values optional Give values or not

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/uri/badges?uri=rfc:3986&type[]=alerts&type[]=citations&type[]=digests&type[]=equivalent-uris&values=1" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/uri/badges?uri=rfc:3986&type[]=alerts&type[]=citations&type[]=digests&type[]=equivalent-uris&values=1",
    "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"
}

Generate a search token

Generates a search token and returns it + the linked identifiers if relevant. As of API version 2, this endpoint is deprecated. It is replaced by /api/v2/search, which returns the same information, but in a more normalized format and with more options. This endpoint will be removed on or after December 31, 2018.

HTTP Request

GET api/v1/token
Query Parameters
ParameterStatusDescription
string required Search for string
autolink required Activate autolink

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/token?string=rfc:3986&autolink=1" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/token?string=rfc:3986&autolink=1",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

{
    "valid": true,
    "string": "rfc:3986",
    "autolink": true,
    "terms": [
        {
            "identifiers": [
                {
                    "autolinked": false,
                    "type": "rfc",
                    "value": 3986
                }
            ],
            "occur": "SHOULD",
            "term": "rfc:3986",
            "valid": true
        }
    ],
    "token": "ee5edb6a-fc9c-410c-b358-d6c5cc26819f"
}

Get search results

Triggers and returns results behind a generated search token. Search tokens are generated using the "Generate a search token." feature. As of API version 2, this endpoint is deprecated. It is replaced by /api/v2/search, which returns the same information, but in a more normalized format and with more options. This endpoint will be removed on or after December 31, 2018.

HTTP Request

GET api/v1/document/search/{token}

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/document/search/{token}" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/document/search/{token}",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

{
    "results": [
        {
            "title": null,
            "source": "salesforce.stackexchange.com",
            "url": "https://salesforce.stackexchange.com/a/193857",
            "identifiers": {
                "rfc": [
                    "3986"
                ]
            },
            "date": "Sep 27, 2017"
        },
        {
            "title": null,
            "source": "ru.stackoverflow.com",
            "url": "https://ru.stackoverflow.com/a/737200",
            "identifiers": {
                "rfc": [
                    "3986"
                ]
            },
            "date": "Oct 28, 2017"
        }
    ],
    "size": 10,
    "hitsNumber": 124,
    "pagesCount": 13
}

Activity and 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. See this page for more information. Requests sent to this endpoint do not count against your quotas.

HTTP Request

GET api/v1/quotas

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v1/quotas" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v1/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"
        }
    }
}

v2

Get citation data, badges, and facets in a single search call.

HTTP Request

GET api/v2/search
Query Parameters
ParameterStatusDescription
query required Search for given query
autolink optional Activate autolink
page optional Citations page
badges optional Activate badges
facets optional Activate facets

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/search?query=domain:wikipedia.org&autolink=1&page=1&badges=1&facets=1" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/search?query=domain:wikipedia.org&autolink=1&page=1&badges=1&facets=1",
    "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"
                }
            }
        ]
    }
}

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

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_cliques": {
        "items": {
            "other": 79865,
            "short_urls": 380000
        },
        "total": 459865
    }
}

Citations

Get citations for a given query

HTTP Request

GET api/v2/citations
Query Parameters
ParameterStatusDescription
query required Search for given query
autolink optional Activate autolink
page optional Given page

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/citations?query=domain:wikipedia.org&autolink=1&page=1" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/citations?query=domain:wikipedia.org&autolink=1&page=1",
    "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 citations count for a given query

HTTP Request

GET api/v2/citations/count
Query Parameters
ParameterStatusDescription
query required Search for given query
autolink optional Activate autolink

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/citations/count" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/citations/count",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

1261

URIs, URLS, and identifiers

Normalize any 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.

HTTP Request

GET api/v2/uri/normal-form
Query Parameters
ParameterStatusDescription
uri 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.

HTTP Request

GET api/v2/uri/equivalent-uris
Query Parameters
ParameterStatusDescription
uri required URI for which we want equivalent URIs
scheme[] optional http, https, or ftp

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/uri/equivalent-uris?uri=bcp:4&scheme[]=http&scheme[]=https&scheme[]=ftp" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/equivalent-uris?uri=bcp:4&scheme[]=http&scheme[]=https&scheme[]=ftp",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

{
    "input": "bcp:4",
    "output": [
        "doi: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/v1/uri/equivalent-urls?uri=xxx:yyy is equivalent to calling api/v1/uri/equivalent-uris?uri=xxx:yyy&scheme=ftp&scheme=http&scheme=https.

HTTP Request

GET api/v2/uri/equivalent-urls
Query Parameters
ParameterStatusDescription
uri required URI for which we want equivalent URLs

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 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.

HTTP Request

GET api/v2/uri/interpolations
Query Parameters
ParameterStatusDescription
uri required URI to be normalized

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/uri/interpolations?uri=bcp:4" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/interpolations?uri=bcp:4",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

Example response

[]

Get URI badges

Badges are simple indicators that summarize what we know about a given URI. See this page for more details.

HTTP Request

GET api/v2/uri/badges
Query Parameters
ParameterStatusDescription
uri required Get badges for this URI
type optional Specify badge types
values optional Give values or not

Example requests

    
curl -X GET" https://cobaltmetrics.com/api/v2/uri/badges?uri=rfc:3986&type[]=alerts&type[]=citations&type[]=digests&type[]=equivalent-uris&values=1" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/badges?uri=rfc:3986&type[]=alerts&type[]=citations&type[]=digests&type[]=equivalent-uris&values=1",
    "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"
}

Activity and 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. See this page for more information. Requests sent to this endpoint do not count against your quotas.

HTTP Request

GET api/v2/quotas

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