Countries and scopes
Two different things are called scope in these docs. A key’s scopes are permissions: which endpoints it may call (Authentication). A workspace’s scope is coverage: which sectors and states its data is read for. This page is about the second.
The workspace’s scope
Section titled “The workspace’s scope”Every workspace follows a set of sectors and either all of India or a set of states and union territories, and may also follow national news (news that names no state). An owner or admin sets this in the dashboard’s setup walkthrough and can change it under Settings.
Every endpoint reads through it:
- Articles (
/signals) are those read as touching a followed sector, in a followed state (or national, if followed). - Stories (
/stories) are those whose sectors and states overlap the scope. A story outside it answers404on/stories/{id}, as if it did not exist. - Outlooks come one per followed sector. Forecasts are those in followed sectors.
- Coordination findings are those whose stories touch the scope.
- Reports and sources are the workspace’s own.
GET /workspace returns the scope, so a program can read it instead of hard-coding it:
"scope": { "sectors": ["energy_power", "politics_governance", "public_order_unrest"], "states": [], "all_india": true, "national": true}Filters narrow; they never widen
Section titled “Filters narrow; they never widen”sector and state filters work inside the scope. A sector or state the workspace does not follow returns an empty list, not an error and never another workspace’s data. A value that is not a sector key or state slug at all is a 400.
Countries
Section titled “Countries”Alethman’s API reads India. Every sector, state, story and outlook it returns is read for Indian coverage, the same as the dashboard’s India view. There is no country parameter in version 1. When other countries come to the API, they will arrive as an addition (a new optional parameter), so code written today keeps working (Versioning).
Foreign and national stories still appear when they are read as touching a followed sector in India: an article with an empty states list is national or foreign news, and appears only when the workspace follows national news.
Sectors
Section titled “Sectors”Nineteen sectors. Pass the key, not the name.
| Key | Sector |
|---|---|
textiles_apparel | Textiles and apparel |
metals_mining | Metals and mining |
trade_imports_exports | Trade, imports and exports |
agriculture_food | Agriculture and food |
energy_power | Energy and power |
infrastructure_transport | Infrastructure and transport |
manufacturing_industry | Manufacturing and industry |
it_telecom_tech | IT, telecom and technology |
pharma_health | Pharma and health |
banking_finance_markets | Banking, finance and markets |
real_estate_construction | Real estate and construction |
public_order_unrest | Public order and unrest |
insurgency_terrorism | Insurgency and terrorism |
crime_law_enforcement | Crime and law enforcement |
defence_borders_foreign | Defence, borders and foreign relations |
politics_governance | Politics and governance |
environment_disaster | Environment and disasters |
labour_employment_education | Labour, employment and education |
media_information | Media and the information space |
States
Section titled “States”Twenty-eight states and eight union territories, as lowercase slugs.
| Slug | State or union territory |
|---|---|
andhra-pradesh | Andhra Pradesh |
arunachal-pradesh | Arunachal Pradesh |
assam | Assam |
bihar | Bihar |
chhattisgarh | Chhattisgarh |
goa | Goa |
gujarat | Gujarat |
haryana | Haryana |
himachal-pradesh | Himachal Pradesh |
jharkhand | Jharkhand |
karnataka | Karnataka |
kerala | Kerala |
madhya-pradesh | Madhya Pradesh |
maharashtra | Maharashtra |
manipur | Manipur |
meghalaya | Meghalaya |
mizoram | Mizoram |
nagaland | Nagaland |
odisha | Odisha |
punjab | Punjab |
rajasthan | Rajasthan |
sikkim | Sikkim |
tamil-nadu | Tamil Nadu |
telangana | Telangana |
tripura | Tripura |
uttar-pradesh | Uttar Pradesh |
uttarakhand | Uttarakhand |
west-bengal | West Bengal |
andaman-and-nicobar-islands | Andaman and Nicobar Islands |
chandigarh | Chandigarh |
dadra-and-nagar-haveli-and-daman-and-diu | Dadra and Nagar Haveli and Daman and Diu |
delhi | Delhi |
jammu-and-kashmir | Jammu and Kashmir |
ladakh | Ladakh |
lakshadweep | Lakshadweep |
puducherry | Puducherry |