API Spec

Trust Metrics API

The Trust Metrics API allows customers to both individually request sites be scored and individually retrieve those scores. It's a simple REST web service API that uses HTTP Basic Authentication for authorization. To obtain an account, please contact us.

Accessing the API

The Trust Metrics API is only available over HTTPS. There is no unencrypted fallback. Additionally, authentication is handled via HTTP Basic Authentication as described in RFC2617.

Requesting Scores

To request that a site be scored, make an HTTP PUT request to:

https://api.trustmetrics.com/v1/site/<URL_ENCODED_SITE_URL>

For example, to request that http://cnn.com be scored, you'd make a PUT request to https://api.trustmetrics.com/v1/site/http%3A%2F%2Fcnn.com Also making a PUT request to https://api.trustmetrics.com/v1/site/cnn.com would work as well.

The response for a successful PUT request will return a 201 response code along with a content body in JSON format that looks like:

{
    "msg": "http://cnn.com was created and will be crawled and scored.",
    "date": "2011-09-14T13:16:10.267Z"
}

The response for an unsuccessful PUT request, say for an invalid URL, will return a 400 response code along with a content body in JSON format that looks like:

{
    "msg": "_this_is_not_a_valid_url is not a valid URL",
    "date": "2011-09-14T13:16:10.267Z"
}

Crawling

Once the PUT request has been made, our web crawler will crawl the site and scores will be produced for the models your account has access to. If you desire a site to be recrawled and rescored, simply make an additional PUT request. The process of crawling and scoring can take several hours, and it should be noted that only one PUT request per day per site will trigger any action.

Retrieving Scores

To retrieve the scores for the sites you've previously made PUT requests for, make an HTTP GET request to the same URL. For example, to fetch the scores for http://cnn.com, you'd make an HTTP GET request with Basic Authentication to https://api.trustmetrics.com/v1/site/http%3A%2F%2Fcnn.com Also making a GET request to https://api.trustmetrics.com/v1/site/cnn.com would work as well.

The response will be in JSON format and is of the form:

{
    "customerId": "3f963348-5798-4857-b2e3-b972a68bfc7a",
    "uri": "http://cnn.com/",
    "activationDate": "2011-09-08T17:24:52.488Z",
    "newScoreRequested": false,
    "lastUpdated": "2011-09-12T18:42:14.046Z",
    "copyright_infringement_bool": "No",
    "profanity_bool": "No",
    "ugc_mod_bool": "Yes",
    "warez_bool": "No",
    "standard_score": "96"
}

The ratings are the scores you have permission to see. If you'd like access to more, please contact us and we can add more ratings to your output.

The activationDate field is the date that you added this site to your library.

The lastUpdated field is when the scores were last updated.

If you'd like the site recrawled and rescored, make a PUT request as described in the section above to get new scores. The newScoreRequested field will be set to true until the scores arrive, and when they do the lastUpdated field will be updated accordingly.

If you request a score for a site that is not in your library, a 404 response code will be returned with a JSON response body like this:

{
    "msg": "http://cnn.com/ was not found in your library. To add it, make an HTTP PUT request to /v1/site/cnn.com",
    "date": "2011-09-14T12:17:31.926Z"
}