To celebrate Thunken's 2nd anniversary and our love of hypertext, we're extracting all citations from the Usenet Archive into Cobaltmetrics. Short service interruptions might occur during this period, and the number of search results for some queries might change as the corpus grows.

API Documentation

v1

Statistics

Get global statistics

This endpoint returns global statistics for all the identifiers indexed by Cobaltmetrics. In the response, the stats object includes three fields for each type of identifier: cardinality contains the number of unique identifiers of this type in the index, count contains the number of identifiers of this type in the index, and name contains a user-friendly expansion of this identifier type's acronym or ID. The special type \* aggregates counts and cardinalities across all other types.

HTTP Request

GET api/v1/statistics/global

Example response

{
    "stats": {
        "*": {
            "cardinality": 291756,
            "count": 1164887,
            "name": "Global"
        },
        "doi": {
            "cardinality": 9108,
            "count": 11055,
            "name": "Digital Object Identifier"
        }
    },
    "_documentsNumber": 14038208
}

Example Requests

    
curl -X GET -G "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);
});
    

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.

HTTP Request

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

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

Example Requests

    
curl -X GET -G "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);
});
    

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 response

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

Example Requests

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

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

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 response

{
    "input": "bcp:4",
    "output": [
        "doi:10.17487\/RFC1917",
        "rfc:1917"
    ]
}

Example Requests

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

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

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 response

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

Example Requests

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

    $.ajax(settings).done(function (response) {
    console.log(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/v1/uri/badges
Query Parameters
ParameterStatusDescription
uri required Get badges for this URI

Example response

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

Example Requests

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

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

Generate a search token.

Generates a search token and returns it + the linked identifiers if relevant.

HTTP Request

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

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

Example Requests

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

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

Get search results.

Triggers and returns results behind a generated search token. Search tokens are generated using the "Generate a search token." feature.

HTTP Request

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

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
}

Example Requests

    
curl -X GET -G "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);
});
    

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

Example Requests

    
curl -X GET -G "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);
});