Skip to content

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.

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 answers 404 on /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
}

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.

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.

Nineteen sectors. Pass the key, not the name.

KeySector
textiles_apparelTextiles and apparel
metals_miningMetals and mining
trade_imports_exportsTrade, imports and exports
agriculture_foodAgriculture and food
energy_powerEnergy and power
infrastructure_transportInfrastructure and transport
manufacturing_industryManufacturing and industry
it_telecom_techIT, telecom and technology
pharma_healthPharma and health
banking_finance_marketsBanking, finance and markets
real_estate_constructionReal estate and construction
public_order_unrestPublic order and unrest
insurgency_terrorismInsurgency and terrorism
crime_law_enforcementCrime and law enforcement
defence_borders_foreignDefence, borders and foreign relations
politics_governancePolitics and governance
environment_disasterEnvironment and disasters
labour_employment_educationLabour, employment and education
media_informationMedia and the information space

Twenty-eight states and eight union territories, as lowercase slugs.

SlugState or union territory
andhra-pradeshAndhra Pradesh
arunachal-pradeshArunachal Pradesh
assamAssam
biharBihar
chhattisgarhChhattisgarh
goaGoa
gujaratGujarat
haryanaHaryana
himachal-pradeshHimachal Pradesh
jharkhandJharkhand
karnatakaKarnataka
keralaKerala
madhya-pradeshMadhya Pradesh
maharashtraMaharashtra
manipurManipur
meghalayaMeghalaya
mizoramMizoram
nagalandNagaland
odishaOdisha
punjabPunjab
rajasthanRajasthan
sikkimSikkim
tamil-naduTamil Nadu
telanganaTelangana
tripuraTripura
uttar-pradeshUttar Pradesh
uttarakhandUttarakhand
west-bengalWest Bengal
andaman-and-nicobar-islandsAndaman and Nicobar Islands
chandigarhChandigarh
dadra-and-nagar-haveli-and-daman-and-diuDadra and Nagar Haveli and Daman and Diu
delhiDelhi
jammu-and-kashmirJammu and Kashmir
ladakhLadakh
lakshadweepLakshadweep
puducherryPuducherry