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."
    },
    "q": {
      "type": "string",
      "description": "French keywords for full-text search across all dataset columns (simple keywords, not sentences). Can be combined with filters, but prefer filters alone when criteria target specific columns. Use query for broad keyword matching across all columns. Examples: \"Jean Dupont\", \"Paris\", \"2025\""
    },
    "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."
    },
    "select": {
      "type": "string",
      "description": "Optional comma-separated list of column keys to include in the results. Useful when the dataset has many columns to reduce output size. If not provided, all columns are returned. Use column keys from describe_dataset. Format: column1,column2,column3 (No spaces after commas). Example: \"nom,age,ville\""
    },
    "sort": {
      "type": "string",
      "description": "Sort order for results. Comma-separated list of column keys. Prefix with - for descending order. Special keys: _score (relevance), _i (index order), _updatedAt, _rand (random), _geo_distance:lon:lat (distance from point, for geolocalized datasets — longitude first, then latitude). Examples: \"population\" (ascending), \"-population\" (descending), \"_geo_distance:2.35:48.85\" (closest to lon=2.35, lat=48.85)"
    },
    "size": {
      "type": "number",
      "description": "Number of rows to return per page (default: 10, max: 50). Increase when you know you need more results upfront to avoid multiple pagination round-trips."
    },
    "page": {
      "type": "number",
      "description": "Page number (default 1)"
    },
    "next": {
      "type": "string",
      "description": "URL from a previous search_data response to fetch the next page of results. When provided, all other parameters (query, filters, select, sort, size) are ignored since the URL already contains them."
    }
  },
  "required": [
    "datasetId"
  ]
}