---
title: "Search & Discovery Layer API"
url: "https://developer.argaam.com/apis/search-discovery-layer-api-production-v1/versions/3ee95f1c-cb8f-47a6-bf01-11e0c199d2ad"
---

# Search & Discovery Layer API

OpenAPI specification document.

````json
{"openapi":"3.0.1","info":{"title":"Search & Discovery Layer API","description":"Cross-cutting discovery and screening: the equity screener (structure, fields, universe, run, peers), the chart universe, and unified company and news lookup.","contact":{"name":"Argaam IT","url":"https://www.argaam.com","email":"developer@argaam.com"},"version":"v1.1"},"paths":{"/api/v1.1/screener/structure":{"get":{"tags":["Screener"],"responses":{"200":{"description":"Success"}},"summary":"Schema describing the screener UI (sections, pages, groups).","description":"Returns the **complete screening schema** that powers the\r\nArgaam web screener. Use this endpoint as the source of truth\r\nfor which fields are available, how they are grouped into\r\npages/sections, and the default UI layout.\r\n            \r\n### Example\r\n```\r\nGET /api/v1.1/screener/structure\r\n```\r\n            \r\n### Response shape\r\nHierarchical: `pages -> sections -> field groups -> fields`.\r\nEach field carries display labels (Ar/En), data type, units,\r\nallowed operators, and grouping metadata.","operationId":"getScreenerStructure","parameters":[]}},"/api/v1.1/screener/fields/config":{"get":{"tags":["Screener"],"responses":{"200":{"description":"Success"}},"summary":"Per-field configuration (formats, units, allowed operators).","description":"Lighter-weight alternative to `/structure`: returns just\r\nthe field-level metadata without page/section grouping.\r\nUseful when building a custom UI or generating screener\r\nqueries programmatically.\r\n            \r\n### Example\r\n```\r\nGET /api/v1.1/screener/fields/config\r\n```","operationId":"getScreenerFieldsConfig","parameters":[]}},"/api/v1.1/screener/sectors":{"get":{"tags":["Screener"],"parameters":[{"name":"marketId","in":"query","schema":{"type":"integer","format":"int32","default":3},"example":3,"description":"Numeric market identifier (e.g. `1` = Tadawul / Saudi main market). Use `GET /api/v1.1/markets` to list valid values. Defaults to `3`."}],"responses":{"200":{"description":"Success"}},"summary":"List sectors","description":"Returns the sectors available on this layer.","operationId":"getScreenerSectors"}},"/api/v1.1/screener/universe":{"get":{"tags":["Screener"],"parameters":[{"name":"countryId","in":"query","description":"Country ID. Default: `1` (Saudi Arabia). Defaults to `1`.","schema":{"type":"integer","format":"int32","default":1},"example":1}],"responses":{"200":{"description":"Success"}},"summary":"Companies grouped by country, market, and sector.","description":"Convenience lookup that returns the **full universe** of listed\r\ncompanies organised under their country -> market -> sector\r\npath. Often used as the seed dataset for cross-market peer\r\nanalysis.\r\n            \r\n### Example\r\n```\r\nGET /api/v1.1/screener/universe?countryId=1\r\n```","operationId":"getScreenerUniverse"}},"/api/v1.1/screener/run/{query}":{"get":{"tags":["Screener"],"parameters":[{"name":"query","in":"path","required":true,"schema":{"type":"string"},"description":"URL-encoded screener query string produced by the screener structure endpoint."}],"responses":{"200":{"description":"Success"}},"summary":"Run a screener query","description":"Executes the URL-encoded screener query built from the structure endpoint and returns the matching companies with the requested columns. Compute-heavy: this endpoint carries its own tighter rate limit, independent of the rest of the layer.","operationId":"getScreenerRunByQuery"}},"/api/v1.1/screener/peers":{"get":{"tags":["Screener"],"responses":{"200":{"description":"Success"}},"summary":"Get peer companies","description":"Returns the peer group for the requested company - sector and size comparable listings used for relative valuation.","operationId":"getScreenerPeers","parameters":[]}},"/api/v1.1/charts/universe":{"get":{"tags":["Charts"],"parameters":[{"name":"countryId","in":"query","description":"Country ID. Default: `1` (Saudi Arabia). Defaults to `1`.","schema":{"type":"integer","format":"int32","default":1},"example":1}],"responses":{"200":{"description":"Discovery tree returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1ResponseOfChartUniverseResponse"},"example":{"success":true,"apiVersion":"1.1","timestamp":"2024-06-01T12:00:00Z","requestId":"req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4","data":{"countryId":1,"tree":[{"id":1,"nameEn":"Saudi Stock Exchange (Tadawul)","nameAr":"السوق المالية السعودية","children":[{"id":4,"nameEn":"Energy","nameAr":"الطاقة","children":[{"id":1,"nameEn":"Saudi Aramco","nameAr":"أرامكو السعودية","children":null}]}]}]},"meta":null,"rateLimit":null}}}}},"summary":"Get the country → markets → sectors → companies discovery tree.","description":"Returns the full hierarchical discovery tree used to populate\r\ncascading dropdowns in the charting tool. Each node contains\r\nan `id`, `name`, and `children` array.\r\n            \r\n**Tip:** For a symbol-specific pre-selection use\r\n`GET /charts/universe/by-symbol?stockSymbol={symbol}`.\r\n            \r\n### cURL Example\r\n```bash\r\ncurl -X GET \"https://api.argaam.com/api/v1.1/charts/universe?countryId=1\" \\\r\n     -H \"Accept: application/json\"\r\n```","operationId":"getChartsUniverse"}},"/api/v1.1/charts/universe/by-symbol":{"get":{"tags":["Charts"],"parameters":[{"name":"countryId","in":"query","description":"Country ID. Default: `1` (Saudi Arabia). Defaults to `1`.","schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"stockSymbol","in":"query","description":"Trading symbol / ticker to pre-select (e.g. `2222`). Defaults to `0`.","schema":{"type":"string","default":"0"},"example":"2222"}],"responses":{"200":{"description":"Discovery tree with pre-selected company returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1ResponseOfChartUniverseBySymbolResponse"},"example":{"success":true,"apiVersion":"1.1","timestamp":"2024-06-01T12:00:00Z","requestId":"req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4","data":{"countryId":1,"symbol":"2222","tree":[{"id":1,"nameEn":"Saudi Stock Exchange (Tadawul)","nameAr":"السوق المالية السعودية","children":[{"id":4,"nameEn":"Energy","nameAr":"الطاقة","children":[{"id":1,"nameEn":"Saudi Aramco","nameAr":"أرامكو السعودية","children":null}]}]}]},"meta":null,"rateLimit":null}}}}},"summary":"Get the discovery tree pre-selected to a specific trading symbol.","description":"Convenience variant of `GET /charts/universe` that pre-populates the\r\ndiscovery tree with the company matching the supplied ticker symbol.\r\nUseful for deep-linking directly to a stock chart from an external page.\r\n            \r\n**Tip:** Use `GET /companies/by-symbol/{symbol}` to resolve the company ID\r\nif you only have the ticker and need additional metadata.","operationId":"getChartsUniverseBySymbol"}}},"components":{"schemas":{"ArticleDetails":{"type":"object","properties":{"articleID":{"type":"integer","format":"int32"},"languageID":{"type":"integer","format":"int32"},"language":{"type":"string","nullable":true,"readOnly":true},"title":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"shortURL":{"type":"string","nullable":true},"publishedOn":{"type":"string","nullable":true},"articleSourceName":{"type":"string","nullable":true},"articleType":{"type":"string","nullable":true,"readOnly":true},"articleTypeNameAr":{"type":"string","nullable":true},"articleTypeNameEn":{"type":"string","nullable":true},"marketTickerIDs":{"type":"string","nullable":true},"marketTickerChartIDs":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true},"companyTickerIDs":{"type":"string","nullable":true},"companyTickerChartIDs":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true},"customAMPCss":{"type":"string","nullable":true}},"additionalProperties":false},"Article":{"type":"object","properties":{"articleID":{"type":"integer","format":"int32"},"languageID":{"type":"integer","format":"int32"},"language":{"type":"string","nullable":true,"readOnly":true},"title":{"type":"string","nullable":true},"publishedOn":{"type":"string","nullable":true},"link":{"type":"string","nullable":true,"readOnly":true},"isLinked":{"type":"boolean"},"linkedToURL":{"type":"string","nullable":true},"isPaid":{"type":"boolean"},"articleSourceName":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"articleType":{"type":"string","nullable":true,"readOnly":true},"articleTypeNameAr":{"type":"string","nullable":true},"articleTypeNameEn":{"type":"string","nullable":true},"marketTickerIDs":{"type":"string","nullable":true},"marketTickerChartIDs":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true},"companyTickerIDs":{"type":"string","nullable":true},"companyTickerChartIDs":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true},"body":{"type":"string","nullable":true},"showDetails":{"type":"boolean"},"iconURL":{"type":"string","nullable":true}},"additionalProperties":false},"ApiV1Meta":{"type":"object","properties":{"page":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"totalRecords":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32","readOnly":true},"hasNextPage":{"type":"boolean","readOnly":true},"hasPreviousPage":{"type":"boolean","readOnly":true}},"additionalProperties":false},"ApiV1RateLimit":{"type":"object","properties":{"limit":{"type":"integer","format":"int32"},"remaining":{"type":"integer","format":"int32"},"reset":{"type":"string","format":"date-time"}},"additionalProperties":false},"ApiV1Response":{"type":"object","properties":{"success":{"type":"boolean"},"apiVersion":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"},"requestId":{"type":"string","nullable":true},"data":{"nullable":true},"meta":{"$ref":"#/components/schemas/ApiV1Meta"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit"}},"additionalProperties":false},"ApiV1Response2":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true for successful responses."},"apiVersion":{"type":"string","description":"Semantic API version (e.g., \"1.0.0\").","nullable":true},"timestamp":{"type":"string","description":"UTC timestamp when the response was generated.","format":"date-time"},"requestId":{"type":"string","description":"Unique request identifier for tracing.","nullable":true},"data":{"description":"The response payload.","nullable":true},"meta":{"$ref":"#/components/schemas/ApiV1Meta2"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit2"}},"additionalProperties":false,"description":"Standardized successful API response wrapper for v1.0.0 endpoints."},"ApiV1RateLimit2":{"type":"object","properties":{"limit":{"type":"integer","description":"Total request quota for the current window.","format":"int32"},"remaining":{"type":"integer","description":"Remaining requests in the current window.","format":"int32"},"reset":{"type":"string","description":"UTC timestamp when the rate limit window resets.","format":"date-time"}},"additionalProperties":false,"description":"Rate limit information returned with each response."},"ApiV1Meta2":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-based).","format":"int32"},"pageSize":{"type":"integer","description":"Number of items per page.","format":"int32"},"totalRecords":{"type":"integer","description":"Total number of records available across all pages.","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages.","format":"int32","readOnly":true},"hasNextPage":{"type":"boolean","description":"Whether there is a next page available.","readOnly":true},"hasPreviousPage":{"type":"boolean","description":"Whether there is a previous page available.","readOnly":true}},"additionalProperties":false,"description":"Pagination and metadata information for collection responses."},"ApiV1ResponseOfChartUniverseResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true for successful responses."},"apiVersion":{"type":"string","description":"Semantic API version (e.g., \"1.0.0\").","nullable":true},"timestamp":{"type":"string","description":"UTC timestamp when the response was generated.","format":"date-time"},"requestId":{"type":"string","description":"Unique request identifier for tracing.","nullable":true},"data":{"$ref":"#/components/schemas/ChartUniverseResponse"},"meta":{"$ref":"#/components/schemas/ApiV1Meta2"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit2"}},"additionalProperties":false,"description":"Standardized successful API response wrapper for v1.0.0 endpoints."},"ChartUniverseResponse":{"type":"object","properties":{"countryId":{"type":"integer","format":"int32"},"tree":{"type":"array","items":{"$ref":"#/components/schemas/ChartUniverseNode"},"nullable":true}},"additionalProperties":false},"ChartUniverseNode":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"nameEn":{"type":"string","nullable":true},"nameAr":{"type":"string","nullable":true},"children":{"type":"array","items":{"$ref":"#/components/schemas/ChartUniverseNode"},"nullable":true}},"additionalProperties":false},"ApiV1ResponseOfChartUniverseBySymbolResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Always true for successful responses."},"apiVersion":{"type":"string","description":"Semantic API version (e.g., \"1.0.0\").","nullable":true},"timestamp":{"type":"string","description":"UTC timestamp when the response was generated.","format":"date-time"},"requestId":{"type":"string","description":"Unique request identifier for tracing.","nullable":true},"data":{"$ref":"#/components/schemas/ChartUniverseBySymbolResponse"},"meta":{"$ref":"#/components/schemas/ApiV1Meta2"},"rateLimit":{"$ref":"#/components/schemas/ApiV1RateLimit2"}},"additionalProperties":false,"description":"Standardized successful API response wrapper for v1.0.0 endpoints."},"ChartUniverseBySymbolResponse":{"type":"object","properties":{"countryId":{"type":"integer","format":"int32"},"symbol":{"type":"string","nullable":true},"tree":{"type":"array","items":{"$ref":"#/components/schemas/ChartUniverseNode"},"nullable":true}},"additionalProperties":false}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey"},"ApiKeyAuthQuery":{"type":"apiKey","in":"query","name":"apikey"}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"url":"https://api.argaam.com","description":"Argaam API Gateway (Production)"}]}
````