Fundamentals Layer API (Sandbox)

Fundamentals Layer API

Get analyst estimates for a company

Returns the analyst estimates for the company identified by stockSymbol.

get
https://api-sandbox.argaam.com/api/v1.1/companies/{stockSymbol}/analyst-estimates

Query Parameters

marketIdinteger(int32)

Numeric market identifier (e.g. 1 = Tadawul / Saudi main market). Use GET /api/v1.1/markets to list valid values.

Default:3

Example:3

periodstring

Time window for the series, e.g. 1d, 1m, 3m, 1y, 5y. Defaults to year.

Default:year

Example:year

Path Parameters

stockSymbolstringrequired

Tadawul stock symbol of the company, e.g. 2222 (Saudi Aramco).

Example:2222

Response

200 application/json

Success

ApiV1Response

* Additional properties are NOT allowed.
successboolean
apiVersionstring | null
timestampstring(date-time)
requestIdstring | null
data
metaobject
* Additional properties are NOT allowed.
Show Child Parameters
rateLimitobject
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1.1/companies/{stockSymbol}/analyst-estimates
 
200 application/json

Get analyst estimates vs. actuals for a company identified by trading symbol.

Returns analyst estimates for the specified financial statement field
(fsFieldId) compared against actual published values for the same
period. Useful for building earnings-surprise charts and consensus
beat/miss dashboards.

Common fsFieldId values

ID Field
54 (default) Net Income
1 Revenue
3 Operating Income
8 EPS

Period values — year (default), quarter, interim.

Tip: For ID-based estimates use
GET /companies/{id}/analyst-estimates.

get
https://api-sandbox.argaam.com/api/v1.1/companies/by-symbol/{symbol}/analyst-estimates

Query Parameters

fiscalYearinteger(int32)

Fiscal year to query (e.g. 2024).

Example:2024

periodstring

Fiscal period type: year (default), quarter, or interim. Defaults to year.

Default:year

Example:year

fsFieldIdinteger(int32)

Financial statement field ID to query. Default 54 (Net Income). Defaults to 54.

Default:54

Example:54

Path Parameters

symbolstringrequired

Company trading symbol / ticker (e.g. 2222 for Saudi Aramco).

Response

200 application/json

Success

ApiV1Response

* Additional properties are NOT allowed.
successboolean
apiVersionstring | null
timestampstring(date-time)
requestIdstring | null
data
metaobject
* Additional properties are NOT allowed.
Show Child Parameters
rateLimitobject
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1.1/companies/by-symbol/{symbol}/analyst-estimates
 
200 application/json

Get analyst opinions for a company

Returns the analyst opinions for the company identified by stockSymbol.

Paginated: use page and pageSize.

get
https://api-sandbox.argaam.com/api/v1.1/companies/{stockSymbol}/analyst-opinions

Query Parameters

marketIdinteger(int32)

Numeric market identifier (e.g. 1 = Tadawul / Saudi main market). Use GET /api/v1.1/markets to list valid values. Defaults to 3.

Default:3

Example:3

pageinteger(int32)

1-based page number. Defaults to 1.

Default:1

Example:1

recordsinteger(int32)

Maximum number of records to return. Defaults to 10.

Default:10

Example:10

Path Parameters

stockSymbolstringrequired

Tadawul stock symbol of the company, e.g. 2222 (Saudi Aramco).

Example:2222

Response

200 application/json

Success

ApiV1Response

* Additional properties are NOT allowed.
successboolean
apiVersionstring | null
timestampstring(date-time)
requestIdstring | null
data
metaobject
* Additional properties are NOT allowed.
Show Child Parameters
rateLimitobject
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1.1/companies/{stockSymbol}/analyst-opinions
 
200 application/json

Get a market-level ratio by market symbol

Returns the market-level ratio identified by marketSymbol.

get
https://api-sandbox.argaam.com/api/v1.1/companies/market-ratios/{marketId}

Query Parameters

fiscalPeriodTypeIdinteger(int32)

Numeric fiscal period type identifier (quarterly / half-yearly / annual). Defaults to 1.

Default:1

Example:1

excludeAramcointeger(int32)

When true, excludes Saudi Aramco (2222) from aggregates so a single mega-cap does not dominate market-level figures. Defaults to 0.

Default:0

Example:0

Path Parameters

marketIdinteger(int32)required

Numeric market identifier (e.g. 1 = Tadawul / Saudi main market). Use GET /api/v1.1/markets to list valid values.

Example:3

Response

200 application/json

Success

ApiV1Response2

Standardized successful API response wrapper for v1.0.0 endpoints.

* Additional properties are NOT allowed.
successboolean

Always true for successful responses.

apiVersionstring | null

Semantic API version (e.g., “1.0.0”).

timestampstring(date-time)

UTC timestamp when the response was generated.

requestIdstring | null

Unique request identifier for tracing.

data

The response payload.

metaobject

Pagination and metadata information for collection responses.

* Additional properties are NOT allowed.
Show Child Parameters
rateLimitobject

Rate limit information returned with each response.

* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1.1/companies/market-ratios/{marketId}
 
200 application/json

Get the company ranking for a metric

Returns companies in the market ranked highest-first by the requested metric.

get
https://api-sandbox.argaam.com/api/v1.1/companies/rankings/{marketId}/{metric}

Path Parameters

marketIdinteger(int32)required

Numeric market identifier (e.g. 1 = Tadawul / Saudi main market). Use GET /api/v1.1/markets to list valid values.

Example:3

metricstringrequired

Ranking metric to sort by (e.g. pe, market-cap, dividend-yield).

Response

200 application/json

Success

ApiV1Response

* Additional properties are NOT allowed.
successboolean
apiVersionstring | null
timestampstring(date-time)
requestIdstring | null
data
metaobject
* Additional properties are NOT allowed.
Show Child Parameters
rateLimitobject
* Additional properties are NOT allowed.
Show Child Parameters
get/api/v1.1/companies/rankings/{marketId}/{metric}
 
200 application/json