Spatial India

Use FIRST, before any other tool, whenever a question names a subject rather than an indicator id — "stunting", "land inequality", "bank credit". Returns matching indicator ids with their unit, source, vintage, caveat and district coverage. Every other tool needs an id from here; ids are not guessable and inventing one fails.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Plain words describing the subject. Every word must appear somewhere in the indicator — prefer two or three words (\"child stunting\", \"land inequality\") over a sentence."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

Use when the question is about one named place — "tell me about Bilaspur", "what is Pune's literacy rate". Resolves an Indian district name, including common alternative spellings, to its objectid and returns its values. Four district names are shared by two states, so if the name is ambiguous this returns every match with its state and no data: ask the user which one, then call again with `state`.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "District name, an alternative spelling, or an objectid."
    },
    "state": {
      "type": "string",
      "description": "State name. Supply this only to disambiguate a repeated district name."
    },
    "indicators": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Indicator ids from find_indicator. Omit to get the district's full profile — every published indicator in one call, which is usually what you want."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Use when the question names two or more places and asks how they differ — "compare Pune and Nagpur on literacy and bank credit". One call, not one get_district per district. Write an ambiguous name as "Bilaspur, Chhattisgarh".

{
  "type": "object",
  "properties": {
    "districts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "District names, \"Name, State\" where a name repeats, or objectids.",
      "minItems": 2
    },
    "indicators": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Indicator ids from find_indicator. At most 5.",
      "minItems": 1
    }
  },
  "required": [
    "districts",
    "indicators"
  ],
  "additionalProperties": false
}

Use for best/worst/highest/lowest questions over many districts — "worst 20 districts for child stunting in Uttar Pradesh". Check the indicator's `polarity` in the result before calling a tail "worst": for a higher-worse indicator the worst districts are `order: "desc"`, for higher-better they are `order: "asc"`. Districts the source never covered sort last in both directions and are never presented as an extreme.

{
  "type": "object",
  "properties": {
    "indicator": {
      "type": "string",
      "description": "One indicator id from find_indicator."
    },
    "scope": {
      "type": "string",
      "description": "A state name to rank within. Omit to rank every district of India."
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "desc = highest value first. Defaults to desc."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "How many districts to return. Defaults to 20."
    }
  },
  "required": [
    "indicator"
  ],
  "additionalProperties": false
}

Use whenever the answer will state a number to a user, and always when asked how a figure was produced, how old it is, or whether it can be trusted. Returns the source, vintage, definition, caveat, estimation method, licence attribution and the citation string for one indicator, or for the dataset as a whole when no indicator is given. Do not describe a number as measured or estimated without checking here — each district carries its own `estimated` flag.

{
  "type": "object",
  "properties": {
    "indicator": {
      "type": "string",
      "description": "An indicator id. Omit for the dataset-wide vintage, sources and citation."
    }
  },
  "additionalProperties": false
}

Use to end an answer with a link the user can open — after any ranking, comparison or district lookup, and whenever they ask to see, map or visualise something. Returns a spatialindia.com/app URL showing exactly those indicators. One indicator draws a choropleth, two draw a bivariate map; a third cannot be expressed in a link and is reported back as dropped.

{
  "type": "object",
  "properties": {
    "indicators": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One or two indicator ids. A third is dropped.",
      "minItems": 1
    },
    "state": {
      "type": "string",
      "description": "A state name to zoom the map to."
    },
    "districts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "District names or objectids to pin. One district also opens its profile."
    },
    "view": {
      "type": "string",
      "enum": [
        "scatter",
        "ranking"
      ],
      "description": "Open the scatter plot or the ranking panel alongside the map."
    }
  },
  "required": [
    "indicators"
  ],
  "additionalProperties": false
}