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

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. 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 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
type optional Give values or not

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. 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 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. 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 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);
});
    

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

Example Requests

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

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

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

Example Requests

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

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

Example Requests

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

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

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 response

1261

Example Requests

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

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 response

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

Example Requests

    
curl -X GET -G "https://cobaltmetrics.com/api/v2/uri/normal-form" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/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/v2/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/v2/uri/equivalent-uris" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/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/v2/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/v2/uri/equivalent-urls" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/equivalent-urls",
    "method": "GET",
        "headers": {
                "Authorization": "<Your API Key>",
                }
    }

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

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 response

[]

Example Requests

    
curl -X GET -G "https://cobaltmetrics.com/api/v2/uri/interpolations" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/interpolations",
    "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/v2/uri/badges
Query Parameters
ParameterStatusDescription
uri required Get badges for this URI
type optional Give values or not

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/v2/uri/badges" \
    -H "Authorization: <Your API Key>"
    
    
var settings = {
    "async": true,
    "crossDomain": true,
    "url": "https://cobaltmetrics.com/api/v2/uri/badges",
    "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/v2/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/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);
});