API: Overview

The root URL for all Parse.ly API requests is

https://api.parsely.com/v2/

Request

Most of our requests are HTTP GET requests. All requests support the following parameters:

Response

All Parse.ly API requests are expected to return one or more matching records.

Successful responses are JSON documents using a “data envelope” format, which has this form:

{
  "data": [{}, {}, {}, ...],
  "meta": {},
  "links": {},
  "success": true
}

Inside the data list, the Parse.ly API typically returns one of the two following content types:

• Posts: Content pages with associated metadata, URL, and metrics
• Metas: Authors, Sections, Tags, etc. with associated metrics

The Analytics API will return a metrics field on both Posts and Metas, containing a mapping of metrics to values.

The Shares API will return a metrics field on both Posts and Metas, containing a mapping of metrics to values.

The meta object contains the list of metrics present in data in the metrics field, as well as how the results were ordered in the sort field.

{
  "data": [
    {
      "metrics": {
        "avg_engaged": 2.793,
        "engaged_minutes": 162,
        "views": 75,
        "visitors": 58
      },
      "title": "...",
    }],
  "success": true,
  "meta": {
    "metrics": [
      "engaged_minutes",
      "avg_engaged",
      "visitors",
      "views"
    ],
    "sort": "avg_engaged"
  },
  "links": {...}
}

The links object contains pagination links. It will always contain a first key, with a link to the first page. A next link will be present if more results are available, otherwise null. A prev link will be available on all pages past the first.

{
  "data": [...],
  "success": true,
  "meta": {...},
  "links": {
    "first": "http://api.parsely.com/v2/...&page=1",
    "next": "http://api.parsely.com/v2/...&page=3",
    "prev": "http://api.parsely.com/v2/...&page=1"
  }
}

The API’s numbers will not match exactly the numbers in our dashboard. This is because the dashboard (and the reports/exports subsystem in the dashboard) always makes a strong effort to get “the most exact counts possible”, whereas the API occasionally accepts a small error rate (1-2% typically) in the name of performance/speed. If you are interested in programmatically exporting exact counts of all your data, you should explore our raw data export options by reaching out to support@parsely.com.

Empty Responses

If you receive an empty response, e.g., {"data": [],..., then it could indicate a mistake in the request. Check the following items of your request:

• spelling
• capitalization
• over-constrained filters

Error Responses

As a matter of practicality, “normal” errors return HTTP Status Code 200 to your client, but encode the error in the JSON document that is returned.

Not Found

If you hit an endpoint below our root endpoint that does not exist, you won’t receive an HTTP 404 status code. You will receive an HTTP 200 status code with the following document contents:

{
  "message": "Not Found",
  "code": 404,
  "success": false
}

Forbidden

If you attempt to access sensitive data with an invalid Site ID (apikey) or secret, you won’t receive an HTTP 403 status code. Instead, you will receive an HTTP 200 status code with the following document contents:

{
  "message": "Forbidden",
  "code": 403,
  "success": false
}

Invalid parameters

If you make a request with parameters that seems invalid (ie passing page anything other than a number), the API will now return what the error is so you can corect it. The HTTP response code from the API will still be 200. Example:

{
  "code": 422,
  "errors":
  {
    "page": ["Not a valid integer."]
  },
  "message": "Bad parameters: page",
  "success": false
}

Other Errors

Other error conditions will take a similar form.

If you receive an HTTP status code other than 200 (e.g. 500 – Internal Server Error), something is wrong with our API, and you should notify us at support@parsely.com. If you receive a “normal” error condition with "code": 500, something may be misconfigured on your account.

Example

An example request to the analytics API might look like this::

GET https://api.parsely.com/v2/analytics/posts?apikey=blog.parsely.com

Response:

{
  "data":[
   {
     "title": "How the Facebook News Feed Changes Have Affected Traffic to News Websites",
     "url": "https://blog.parse.ly/post/977/how-the-facebook-news-feed-changes-have-affected-traffic-to-news-websites/",
     "_hits": 274,
     "pub_date": "2013-12-19T00:24:29",
     "author": "Clare O.",
     "section": "Analytics That Matter",
     "tags": ["blog", "analytics"],
     "thumb_url_medium": "http://c0001566.cdn1.cloudfiles.rackspacecloud.com/medium_3d2dbbd7b44f855e2c263551588e1b2db499109f.jpg",
     "image_url": "https://blog.parse.ly/wp-content/uploads/2013/12/authority-report-03-graph-top-domains-small.png",
     "full_content_word_count": 435,
     "metadata": "{"num_images": 3}"
     "metrics": {
      "views": 274
     }
   },
   // ... other top documents ...
  ]
}

Triggering a new article crawl

The workflow for triggering a new crawl of an article is slightly different from the calls described above. Refer to our documentation on that here.