--- title: "Query data" method: GET path: "/tesseract/data.{extension}" tags: ["TesseractModule"] --- # Query data `GET /tesseract/data.{extension}` ## Request - Base URL: `https://api.datausa.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.datausa.io/tesseract/data.{extension}` - Auth: none declared Execute a request for data from the backend server. ## Path parameters - `extension` 'csv' | 'csvbom' | 'xlsx' | 'jsonarrays' | 'jsonrecords' | 'parquet' | 'tsv' | 'tsvbom', required: Define the extensions available to the user and how to response to them. ## Query parameters - `cube` string, required: The name of the cube to work with. - `drilldowns` string, required: A list of the level names to slice the bulk of the aggregated data. - `measures` string, required: A list of the measure names to retrieve from the aggregated data. - `alias` string, nullable: Custom column aliases for levels or measures. Matching "Column ID" headers are updated automatically when present. Multiple mappings are separated by semicolons (;) Format: Column:Alias;Column2:Alias2 - Column: The exact column label to rename (e.g., "Exporter Country", "Population") - Alias: The new label to use in the response Examples: "Exporter Country:Country;Population:Pop - `aliases` string, nullable: Custom column aliases for levels or measures. Matching "Column ID" headers are updated automatically when present. Multiple mappings are separated by semicolons (;) Format: Column:Alias;Column2:Alias2 - Column: The exact column label to rename (e.g., "Exporter Country", "Population") - Alias: The new label to use in the response Examples: "Exporter Country:Country;Population:Pop - `locale` string, nullable - `limit` string: Controls how many results to return and from which position to start. Format: A single number (limit) or two numbers separated by comma (limit,offset) - limit: Maximum number of items to return - offset: Starting position (0-based index) in the full result set Examples: "10" returns first 10 items, "10,20" returns 10 items starting from position 20 - `parents` string: Include parent level information for drilldown dimensions Options: - "true" or "1": Include parents for all drilldowns - "false" or "0": Exclude all parents (default) - "Level1,Level2": Include parents only for specified levels Examples: "true", "Country,State" - `properties` string, nullable: Additional properties to include for each dimension member - `ranking` string: Add ranking numbers to measures in the results. Options: - "true" or "1": Add rankings for all measures - "false" or "0": No rankings (default) - "Measure1,Measure2": Add rankings only for specified measures Use "-" prefix for descending order: "-Population" ranks Population in descending order. Equal values get the same rank, with gaps for ties. - `sort` string: Controls the order of results by measures or properties. Format: field or field.order - field: Name of the measure or property to sort by - order: "asc" (ascending) or "desc" (descending), defaults to "asc" if not specified The system first looks for a measure with this name, then for a property. Examples: "Population", "Population.desc", "Country.asc" - `sparse` boolean: Control whether to return only rows with data or all possible combinations. - true (default): Return only rows that have at least one non-null measure value - false: Return all possible dimension combinations for requested drilldowns (full cardinality). Measures without values will be null. Warning: Setting to false may return very large datasets, specially when many drilldowns are used. - `time` string, nullable: Filter data by time periods using various restriction types. Format: level.constraint - level: Time dimension level name as defined in the cube (e.g., "Year", "Month") or time scale ("year", "quarter", "month", "day") - constraint: Time restriction type with parameters Constraint types (periods are defined by the time dimension level): - `complete`: Return all available time periods (only for "year" and "quarter" scales) - `latest.N`: Return the N most recent records, regardless of time continuity (e.g., "latest.5" for last 5 records) - `oldest.N`: Return the N earliest records, regardless of time continuity (e.g., "oldest.3" for first 3 records) - `trailing.N`: Return the records available in the last N periods (e.g., "trailing.12" for records within the last 12 periods) - `leading.N`: Return the records available in the first N periods (e.g., "leading.3" for records within the first 3 periods) - expr.condition: Custom time filtering using comparison operators (e.g., "gt.2020", "gte.2020.and.lt.2022") Examples: `Year.latest.5` (last 5 years), `Month.trailing.12` (last 12 months), `Quarter.complete` (all quarters) - `top` string, nullable: Return only the top/bottom results grouped by specified levels. Format: amount.level[,level...].measure.order - amount: Number of top/bottom results to return (integer > 0) - level[,level...]: One or more levels to group by (comma-separated) - measure: The measure to rank by - order: "desc" for top results, "asc" for bottom results Examples: `10.Country.Population.desc` (top 10 countries by population) or `5.State,City.Sales.asc` (bottom 5 state-city combinations by sales) This groups the data by the specified levels, then returns only the top or bottom results based on the measure value. - `growth` string, nullable: Calculate growth rates for measures over time. Format: time_level.measure.params - time_level: The time dimension level (e.g., "Year", "Month", "Quarter") - measure: The measure to calculate growth for - params: Either `fixed.member_id` (compare to specific time period) or `period.amount` (compare consecutive periods) Examples: `Year.Population.fixed.2020` (growth compared to 2020) or `Month.Sales.period.1` (month-over-month growth) This adds period difference and growth percentage columns showing the change in measure values over time. - `exclude` string: Specifies which dimension members to exclude from the results. Format: LevelName:member1,member2;LevelName2:member3,member4 - LevelName: The name of the dimension level - member1,member2: Comma-separated list of member IDs to exclude Examples: `Country:XX,YY` or `Year:2020;Country:XX,YY` - `include` string: Specifies which dimension members to include in the results. Format: LevelName:member1,member2;LevelName2:member3,member4 - LevelName: The name of the dimension level - member1,member2: Comma-separated list of member IDs to include Examples: `Country:US,CA,MX` or `Year:2020,2021;Country:US,CA` For backward compatibility, you can also use the level name directly as a parameter: `&Country=US,CA,MX` is equivalent to `&include=Country:US,CA,MX`. This is not recommended though, as it may cause confusion. - `filters` string[]: Apply filters to measure values in the results. Format: measure.operator.value or measure.operator1.value1.logic.operator2.value2 - measure: Name of the measure to filter - operator: gt, gte, eq, neq, lt, lte (comparisons) or in, nin (membership) or isnull, notnull (nullability) - value: Numeric value for comparisons, list for membership, none for nullability - logic: "and", "or", "xor" (to combine multiple conditions) Examples: - `Population.gt.1000000` - `Sales.gte.1000.and.lt.5000` - `Revenue.in.100,200,300` - `Profit.isnull` - `token` string, nullable ## Headers - `authorization` string, nullable - `x-tesseract-jwt` string, nullable ## Response `200` Successful Response - unknown ## Other responses - `422`: Validation Error ## Changes - **2026-10-27** `433b34956d9c`: 3 info - added the new optional `query` request parameter `alias` - added the new optional `query` request parameter `sparse` - `query` request parameter `aliases` was deprecated [Operation history](https://skmtc.dev/datausa/apis/datausa-api/changes/tesseract/data.:extension/get.md) --- [API](https://skmtc.dev/datausa/apis/datausa-api.md) - [All operations](https://skmtc.dev/datausa/apis/datausa-api/llms.txt) - [OpenAPI document](https://skmtc.dev/datausa/apis/datausa-api/revisions/433b34956d9c?raw)