datafair.cloud

{
  "type": "object",
  "properties": {
    "datasetId": {
      "type": "string",
      "description": "The exact dataset ID from the \"id\" field in list_datasets results. Do not use the title or slug."
    },
    "groupByColumns": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Columns to GROUP BY (like SQL GROUP BY). These define the categories/buckets, NOT the column to compute metrics on. Use column keys from describe_dataset (min 1, max 3)."
    },
    "metric": {
      "type": "object",
      "properties": {
        "column": {
          "type": "string",
          "description": "The column to compute the metric ON (e.g., \"salary\" for average salary). This is NOT the grouping column. Use column keys from describe_dataset."
        },
        "type": {
          "type": "string",
          "description": "Metric to compute on each group. \"count\" counts rows per group (identical to omitting the metric parameter — does NOT count non-null values of the specified column)."
        }
      },
      "description": "Optional metric to compute ON EACH GROUP. If not provided, defaults to counting rows per group."
    },
    "filters": {
      "type": "object",
      "description": "Column filters as key-value pairs: column_key + suffix, all values strings. Example: { \"ville_eq\": \"Paris\", \"age_lte\": \"30\", \"nom_search\": \"Jean\" }. Suffixes include _eq, _in, _gt/_lt, _search and more; if one is rejected the 400 error lists what the column supports. Never _c_-prefix a column filter (use ville_eq, not _c_ville_eq).",
      "properties": {}
    },
    "bbox": {
      "type": "string",
      "description": "Bounding box \"lonMin,latMin,lonMax,latMax\" (lon before lat), e.g. \"-2.5,43,3,47\". Geolocalized datasets only."
    },
    "geoDistance": {
      "type": "string",
      "description": "Proximity filter \"lon,lat,distance\" (lon first), e.g. \"2.35,48.85,10km\"; distance \"0\" = point-in-polygon. Geolocalized datasets only."
    },
    "dateMatch": {
      "type": "string",
      "description": "Date \"YYYY-MM-DD\" (single day) or \"YYYY-MM-DD,YYYY-MM-DD\" (range), e.g. \"2023-11-21\". Temporal datasets only."
    },
    "sort": {
      "type": "string",
      "description": "Sort order for aggregation results. Use special keys: \"count\" or \"-count\" (by row count asc/desc), \"key\" or \"-key\" (by column value asc/desc), \"metric\" or \"-metric\" (by metric value asc/desc). Default: sorts by metric desc (if metric specified), then count desc. Example: \"-count\" to sort by most frequent values first"
    }
  },
  "required": [
    "datasetId",
    "groupByColumns"
  ]
}