Acuity Analyst Ratings Extended API

Basic Concepts

The Analyst Ratings Extended API returns two analyst datasets for equities in a single call:

• Consensus – monthly snapshots of analyst recommendations split into five rating buckets (Strong Buy, Buy, Hold, Sell, Strong Sell). Each snapshot also carries a calculated consensus score and consensus rating.
• Price Targets – monthly snapshots of analyst price targets (high, low, mean and median), with the number of analysts contributing a target.

The API supports:

• the latest snapshot or the full history over a date range
• up to 50 stocks per request
• lookup by Acuity Asset ID, ISIN code, or both in the same request
• a clear distinction between "this stock has no analyst coverage" and "this identifier was not recognised"

The existing POST /api/asset/analystratings endpoint (latest Buy/Hold/Sell counts and a ConsensusPhrase over a rolling 90 days) is unchanged and remains available.

Consensus Calculation

Each consensus snapshot carries a numeric ConsensusScore, from −2 (Strong Sell) to +2 (Strong Buy), and a ConsensusRating label derived from it. The score lets you rank stocks; the rating gives you a label to display.

Weights

Formula

N = StrongBuy + Buy + Hold + Sell + StrongSell

ConsensusScore = 2 x StrongBuy + 1 x Buy + 0 x Hold - 1 x Sell - 2 x StrongSell

N is the total number of consensus ratings in the snapshot. It is not the price-target AnalystCount: the two datasets come from different coverage sets and are not reconciled.

The score is rounded to 2 decimal places (half away from zero), and the rating is then derived from the rounded score. When N = 0, both ConsensusScore and ConsensusRating are null; the snapshot is still returned with its zero counts.

Consensus Rating Thresholds

Example

Apple Inc, consensus snapshot for October 2026:

The weighted sum is 37 and N = 49. The score is 37 / 49 = 0.7551, which rounds to 0.76, giving a rating of Buy.

REST API

Documentation

• Overview: https://api.acuitytrading.com/
• Swagger URL: https://api.acuitytrading.com/swagger/index.html
• Endpoint: POST /api/asset/analystratings/extended

Authentication

Documentation URL: https://api.acuitytrading.com/Security

Exchange your username and password for a Bearer token that you can pass with any request. The token is valid for 14 days.

Sample Request

curl -L -X POST 'https://api.acuitytrading.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=YOUR_USERNAME' \
--data-urlencode 'password=YOUR_PASSWORD'

Sample Response

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
 "token_type": "bearer",
 "expires_in": 1209600,
 "userName": "YOUR_USERNAME"
}

Pass the access_token in the Authorization header of every request: Authorization: Bearer YOUR_BEARER_TOKEN. A request without a valid token receives 401 Unauthorized.

Request Model

AssetIds and ISINCodes can be combined in one request, up to 50 identifiers in total. If both StartDate and EndDate are omitted, the response contains the latest snapshot only.

Response Model

The response is an array of asset objects.

Asset object

Consensus object

PriceTarget object

Response Behaviour

Latest and History Modes

• Latest mode (no StartDate or EndDate): each series contains one item, the most recent snapshot for that asset, or is empty.
• History mode (StartDate and EndDate supplied): each series contains every snapshot dated between StartDate and EndDate, inclusive. Consensus and PriceTargets are filtered independently.

Snapshot Cadence

• Consensus snapshots are monthly and dated the first day of the month, for example 2026-10-01T00:00:00.
• Price Targets snapshots are dated on the day of the last price-target update in each calendar month, for example 2026-10-22T00:00:00. There is at most one per month, and a month with no update has no snapshot.

Because consensus snapshots are dated the 1st of the month, a range that does not include the 1st of any month (for example 5–15 October) returns no consensus snapshot. To chart monthly history, start your range on the 1st of a month.

Identifiers and Ordering

• ISIN codes are matched case-insensitively and resolved to Acuity Asset IDs.
• An asset requested more than once, by AssetId, ISIN or both, appears once in the response.
• Assets are returned in ascending AssetId order, whatever order they were requested in.
• Series items are returned newest first.

Coverage and Unknown Identifiers

• A well-formed AssetId or ISIN that does not match any asset is omitted from the response. It is not treated as an error. If no identifier matches, the response is an empty array [].
• A known asset with no analyst coverage is returned with empty Consensus and PriceTargets arrays. This lets you tell "no coverage" apart from "identifier not recognised".
• A consensus snapshot where every count is 0 is still returned, with ConsensusScore and ConsensusRating set to null.

Consensus and Price-Target Coverage

Consensus counts and the price-target AnalystCount come from different coverage sets and are not reconciled. For example, Sony Group Corp has 31 consensus ratings (8 + 20 + 3) but an AnalystCount of 30.

Common Requests

All responses below are live data from the production API.

Retrieve the latest ratings for a stock by Asset ID

Sample Request

curl -L 'https://api.acuitytrading.com/api/asset/analystratings/extended' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
-d '{
"AssetIds": [113240]
}'

Sample Response

[
{
 "AssetId": 113240,
 "AssetName": "Sony Group Corp",
 "ISIN": "US8356993076",
 "Currency": "USD",
 "Consensus": [
{
 "Date": "2026-10-01T00:00:00",
 "StrongBuyCount": 8,
 "BuyCount": 20,
 "HoldCount": 3,
 "SellCount": 0,
 "StrongSellCount": 0,
 "ConsensusScore": 1.16,
 "ConsensusRating": "Buy"
 }
],
 "PriceTargets": [
{
 "Date": "2026-10-22T00:00:00",
 "AnalystCount": 30,
 "TargetHigh": 38.9,
 "TargetLow": 16.76,
 "TargetMean": 29.42,
 "TargetMedian": 29.46
 }
]
}
]

Retrieve the latest ratings for several stocks by ISIN

ISIN matching is case-insensitive, so the lowercase Apple ISIN below still matches. Assets are returned in ascending AssetId order.

Sample Request

curl -L 'https://api.acuitytrading.com/api/asset/analystratings/extended' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
-d '{
"ISINCodes": ["US8356993076", "us0378331005"]
}'

Sample Response

[
{
 "AssetId": 3,
 "AssetName": "Apple Inc",
 "ISIN": "US0378331005",
 "Currency": "USD",
 "Consensus": [
{

 "Date": "2026-10-01T00:00:00",
 "StrongBuyCount": 11,
 "BuyCount": 20,
 "HoldCount": 14,
 "SellCount": 3,
 "StrongSellCount": 1,
 "ConsensusScore": 0.76,
 "ConsensusRating": "Buy"
 }
],
 "PriceTargets": [
{
 "Date": "2026-10-20T00:00:00",
 "AnalystCount": 43,
 "TargetHigh": 425.25,
 "TargetLow": 217.15,
 "TargetMean": 331.5,
 "TargetMedian": 336.6
 }
]
},
{
 "AssetId": 113240,
 "AssetName": "Sony Group Corp",
 "ISIN": "US8356993076",
 "Currency": "USD",
 "Consensus": [
{
 "Date": "2026-10-01T00:00:00",
 "StrongBuyCount": 8,
 "BuyCount": 20,
 "HoldCount": 3,
 "SellCount": 0,
 "StrongSellCount": 0,
 "ConsensusScore": 1.16,
 "ConsensusRating": "Buy"
 }
],
 "PriceTargets": [
{
 "Date": "2026-10-22T00:00:00",
 "AnalystCount": 30,
 "TargetHigh": 38.9,
 "TargetLow": 16.76,
 "TargetMean": 29.42,
 "TargetMedian": 29.46
 }
]
}
]

Retrieve rating history over a date range

Sony is requested twice here, once by AssetId and once by ISIN, and appears once in the response. July 2026 has a consensus snapshot but no price-target update, so PriceTargets has three items.

Sample Request

curl -L 'https://api.acuitytrading.com/api/asset/analystratings/extended' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
-d '{
"AssetIds": [113240],
"ISINCodes": ["US8356993076"],
"StartDate": "2026-07-01T00:00:00",
"EndDate": "2026-10-30T00:00:00"
}'

Sample Response

[
{
 "AssetId": 113240,
 "AssetName": "Sony Group Corp",
 "ISIN": "US8356993076",
 "Currency": "USD",
 "Consensus": [
{ "Date": "2026-10-01T00:00:00", "StrongBuyCount": 8, "BuyCount": 20, "HoldCount": 3, "SellCount": 0, "StrongSellCount": 0, "ConsensusScore": 1.16, "ConsensusRating": "Buy" },
{ "Date": "2026-09-01T00:00:00", "StrongBuyCount": 8, "BuyCount": 20, "HoldCount": 3, "SellCount": 0, "StrongSellCount": 0, "ConsensusScore": 1.16, "ConsensusRating": "Buy" },
{ "Date": "2026-08-01T00:00:00", "StrongBuyCount": 8, "BuyCount": 20, "HoldCount": 3, "SellCount": 0, "StrongSellCount": 0, "ConsensusScore": 1.16, "ConsensusRating": "Buy" },
{ "Date": "2026-07-01T00:00:00", "StrongBuyCount": 9, "BuyCount": 20, "HoldCount": 2, "SellCount": 0, "StrongSellCount": 0, "ConsensusScore": 1.23, "ConsensusRating": "Buy" }
],
 "PriceTargets": [
{ "Date": "2026-10-22T00:00:00", "AnalystCount": 30, "TargetHigh": 38.9, "TargetLow": 16.76, "TargetMean": 29.42, "TargetMedian": 29.46 },
{ "Date": "2026-09-13T00:00:00", "AnalystCount": 30, "TargetHigh": 40.28, "TargetLow": 17.35, "TargetMean": 30.63, "TargetMedian": 30.82 },
{ "Date": "2026-08-27T00:00:00", "AnalystCount": 30, "TargetHigh": 39.12, "TargetLow": 16.85, "TargetMean": 29.5, "TargetMedian": 29.93 }
]
}
]

Unknown identifiers and assets with no coverage

AssetId 999999999 and ISIN XS0000000000 are well-formed but unknown, so they are omitted. EURUSD (AssetId 50) is a known asset with no analyst coverage, so it is returned with empty arrays.

Sample Request

curl -L 'https://api.acuitytrading.com/api/asset/analystratings/extended' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
-d '{
"AssetIds": [50, 999999999],
"ISINCodes": ["XS0000000000"]
}'

Sample Response

[
{
 "AssetId": 50,
 "AssetName": "EURUSD",
 "ISIN": "",
 "Currency": "",
 "Consensus": [],
 "PriceTargets": []
}
]

If none of the requested identifiers match, the response is an empty array: [].

Errors

Errors are returned in the standard ProblemDetails format, with a detail field explaining the cause.

Validation errors (400 Bad Request)

Sample Request

curl -L 'https://api.acuitytrading.com/api/asset/analystratings/extended' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
-d '{
"AssetIds": [113240],
"StartDate": "2026-10-01T00:00:00",
"EndDate": "2026-07-01T00:00:00"
}'

Sample Response

{
 "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
 "title": "One or more validation errors occurred.",
 "status": 400,
 "detail": "StartDate must be on or before EndDate.",
 "traceId": "00-2d3ba8047f40523d2a81081c294325f2-abca3170eb285809-00"
}

Authentication and permission errors

Sample 403 Response

{
 "title": "Forbidden",
 "status": 403,
 "detail": "The user does not have access to Analyst Ratings data."
}