Fundamentals Layer API (Production)

Fundamentals Layer API

Get a market-level ratio by market symbol

Returns the market-level ratio identified by marketSymbol.

get
https://api.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.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

Get the bottom 20 companies by metric

Returns the twenty lowest-ranked companies in the market for the requested metric.

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

Query Parameters

periodstring

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

Default:quarter

Example:year

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}/lowest-20/{metric}
 
200 application/json

Get analyst estimates aggregated across all companies in a market.

Returns consensus analyst estimates for a specific financial statement
field across all coverage companies in the market for the given fiscal
year and period.

Common fsFieldId values

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

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

Tip: For a single company’s estimates use
GET /companies/{companyId}/analyst-estimates.

get
https://api.argaam.com/api/v1.1/markets/{marketId}/analyst-estimates

Query Parameters

yearinteger(int32)

Fiscal year (e.g. 2024).

Example:2023

periodstring

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

Default:year

Example:year

fiscalPeriodstring

Specific sub-period: year, q1–q4, i1–i3. Defaults to the period type’s natural value.

Default:

Example:year

fsFieldIdinteger(int32)

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

Default:54

Example:54

Path Parameters

marketIdinteger(int32)required

Market ID (e.g. 1 for Saudi Tadawul).

Example:3

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/markets/{marketId}/analyst-estimates
 
200 application/json

Get aggregated financial results for all companies in a market.

Returns the published financial statement results for all companies
in the specified market for the given fiscal year and period.

Useful for building a market-wide results summary table or for
comparing company-level performance within the same period.

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

Tip: To drill into a single company’s results within this market use
GET /markets/{marketId}/financial-results/{companyId}.

get
https://api.argaam.com/api/v1.1/markets/{marketId}/financial-results

Query Parameters

yearinteger(int32)

Fiscal year (e.g. 2023).

Example:2023

periodstring

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

Default:year

Example:year

fiscalPeriodstring

Specific sub-period: year, q1–q4, i1–i3.

Default:

Example:year

Path Parameters

marketIdinteger(int32)required

Market ID (e.g. 1 for Saudi Tadawul).

Example:3

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/markets/{marketId}/financial-results
 
200 application/json