{"_id":"@centoic/ipeds-fetch","_rev":"4-fc1041d12fc95ac3a23f37842ec96035","name":"@centoic/ipeds-fetch","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@centoic/ipeds-fetch","version":"0.1.0","keywords":["ipeds","nces","education","data","cli","download"],"license":"MIT","_id":"@centoic/ipeds-fetch@0.1.0","maintainers":[{"name":"jasontyping","email":"npm.dev@jasonroth.net"}],"homepage":"https://github.com/centoic/ipeds-fetch#readme","bugs":{"url":"https://github.com/centoic/ipeds-fetch/issues"},"bin":{"ipeds-fetch":"bin/ipeds-fetch.js"},"dist":{"shasum":"7e47969ca84a5993d0becb73af377e76dbd2f4df","tarball":"https://registry.npmjs.org/@centoic/ipeds-fetch/-/ipeds-fetch-0.1.0.tgz","fileCount":56,"integrity":"sha512-emGK0UnXOFso0J2U03F1sth6PL+W+ns0nrGWS1o59yCYioG72tSPn9QE70hV61o5hBR1Diz2RbAq2QV2yWXDfQ==","signatures":[{"sig":"MEYCIQDyD7b1xTKjllbV4xZHpFuOPCVuzIiff5e+M/Kms9ScdQIhALotHEUMm0sSo6ftfzZ7JXOyV2NGqMS6V1H/NxtzxaYv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81348},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"31b7702c98d233c1a2d45cbd69da811c9ea503ea","scripts":{"lint":"eslint .","build":"tsc","prepare":"npm run build","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jasontyping","email":"npm.dev@jasonroth.net"},"repository":{"url":"git+https://github.com/centoic/ipeds-fetch.git","type":"git"},"_npmVersion":"10.8.2","description":"CLI tool and library for downloading IPEDS data files","directories":{},"_nodeVersion":"22.5.1","dependencies":{"unzipper":"^0.12.3","playwright":"^1.58.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.0.0","globals":"^16.0.0","prettier":"2.8.8","@eslint/js":"^9.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@types/unzipper":"^0.10.10","@tsconfig/node20":"^20.1.4","typescript-eslint":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ipeds-fetch_0.1.0_1778637086906_0.7604943185219311","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@centoic/ipeds-fetch","version":"0.2.0","keywords":["ipeds","nces","education","data","cli","download"],"license":"MIT","_id":"@centoic/ipeds-fetch@0.2.0","maintainers":[{"name":"jasontyping","email":"npm.dev@jasonroth.net"}],"homepage":"https://github.com/centoic/ipeds-fetch#readme","bugs":{"url":"https://github.com/centoic/ipeds-fetch/issues"},"bin":{"ipeds-fetch":"bin/ipeds-fetch.js"},"dist":{"shasum":"b83dfe5abe0e6483c9fdf8ee58814d56606fbda2","tarball":"https://registry.npmjs.org/@centoic/ipeds-fetch/-/ipeds-fetch-0.2.0.tgz","fileCount":56,"integrity":"sha512-pJOXFaJjJcL/Zw/9srkCnxGBKbwIOv04I+zudBfZe2suGyIB4VydocJxmEeUUlHvhxzrjOUoMZ+ys9wQTgRq8Q==","signatures":[{"sig":"MEQCICNYFbGDjaD7Q7mdRfj+VHoo55SeorCmFdiOgF4+k8scAiB5tlHu0CeP11t3kL9g8YLX2yxWeghdplfu2FvN9S3m+g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89853},"main":"dist/index.js","type":"module","_from":"file:centoic-ipeds-fetch-0.2.0.tgz","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"scripts":{"lint":"eslint .","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jasontyping","email":"npm.dev@jasonroth.net"},"_resolved":"/tmp/c2c5c5cd599e06077365680aae753315/centoic-ipeds-fetch-0.2.0.tgz","_integrity":"sha512-pJOXFaJjJcL/Zw/9srkCnxGBKbwIOv04I+zudBfZe2suGyIB4VydocJxmEeUUlHvhxzrjOUoMZ+ys9wQTgRq8Q==","repository":{"url":"git+https://github.com/centoic/ipeds-fetch.git","type":"git"},"_npmVersion":"10.8.2","description":"CLI tool and library for downloading IPEDS data files","directories":{},"_nodeVersion":"22.5.1","dependencies":{"xlsx":"^0.18.5","unzipper":"^0.12.3","playwright":"^1.58.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.0.0","globals":"^16.0.0","prettier":"2.8.8","@eslint/js":"^9.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@types/unzipper":"^0.10.10","@tsconfig/node20":"^20.1.4","typescript-eslint":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ipeds-fetch_0.2.0_1778798642793_0.23952212105919113","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@centoic/ipeds-fetch","version":"0.2.1","keywords":["ipeds","nces","education","data","cli","download"],"license":"MIT","_id":"@centoic/ipeds-fetch@0.2.1","maintainers":[{"name":"jasontyping","email":"npm.dev@jasonroth.net"}],"homepage":"https://github.com/centoic/ipeds-fetch#readme","bugs":{"url":"https://github.com/centoic/ipeds-fetch/issues"},"bin":{"ipeds-fetch":"bin/ipeds-fetch.js"},"dist":{"shasum":"59839bd814e457b904e9d421972585411032b46a","tarball":"https://registry.npmjs.org/@centoic/ipeds-fetch/-/ipeds-fetch-0.2.1.tgz","fileCount":56,"integrity":"sha512-xU9u9M6wfExHL4tMhaZFFdJT4uzqjK1VLziHv866dCIhbbYwoZRAzfyjZ18id/rwfioE60BBj6ihf8CuRCUneQ==","signatures":[{"sig":"MEQCIDSOFNg759eAAKRiv8ILl72dpLzMDTiTr0SDNqMG5E1lAiA62vUaNVPmT+UYi3+jIymUWZPkd/CRvW4In3+Ii1+n7w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":89853},"main":"dist/index.js","type":"module","_from":"file:centoic-ipeds-fetch-0.2.1.tgz","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"scripts":{"lint":"eslint .","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"jasontyping","email":"npm.dev@jasonroth.net"},"_resolved":"/tmp/8198e48b1cbd1b5ead431f4d7a8b9ff9/centoic-ipeds-fetch-0.2.1.tgz","_integrity":"sha512-xU9u9M6wfExHL4tMhaZFFdJT4uzqjK1VLziHv866dCIhbbYwoZRAzfyjZ18id/rwfioE60BBj6ihf8CuRCUneQ==","repository":{"url":"git+https://github.com/centoic/ipeds-fetch.git","type":"git"},"_npmVersion":"10.8.2","description":"CLI tool and library for downloading IPEDS data files","directories":{},"_nodeVersion":"22.5.1","dependencies":{"xlsx":"^0.18.5","unzipper":"^0.12.3","playwright":"^1.58.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.0.0","globals":"^16.0.0","prettier":"2.8.8","@eslint/js":"^9.0.0","typescript":"^5.0.0","@types/node":"^20.0.0","@types/unzipper":"^0.10.10","@tsconfig/node20":"^20.1.4","typescript-eslint":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ipeds-fetch_0.2.1_1778961087505_0.3648627174775194","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@centoic/ipeds-fetch","license":"MIT","repository":{"type":"git","url":"git+https://github.com/centoic/ipeds-fetch.git"},"homepage":"https://github.com/centoic/ipeds-fetch#readme","bugs":{"url":"https://github.com/centoic/ipeds-fetch/issues"},"keywords":["ipeds","nces","education","data","cli","download"],"engines":{"node":">=22.0.0"},"version":"0.3.0","description":"CLI tool and library for downloading IPEDS data files","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"ipeds-fetch":"bin/ipeds-fetch.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","prepare":"tsc","prepublishOnly":"tsc && eslint . && tsc --noEmit","lint":"eslint .","typecheck":"tsc --noEmit"},"devDependencies":{"@eslint/js":"9.39.4","@tsconfig/node22":"22.0.5","@types/node":"20.19.43","@types/unzipper":"0.10.11","eslint":"9.39.4","globals":"16.5.0","prettier":"2.8.8","typescript":"5.9.3","typescript-eslint":"8.61.1"},"dependencies":{"playwright":"1.61.1","unzipper":"0.12.5","xlsx":"https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"},"pnpm":{"onlyBuiltDependencies":[]},"packageManager":"pnpm@10.33.4","_id":"@centoic/ipeds-fetch@0.3.0","gitHead":"1134adbb523605b23bad2276508527f3564f1774","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-98hjAPJPxu5KleXZewxu5i3zCNOhXZk7MWdKUWVbXlpLGeciC4v5kL1EV++Ea/4bVPvtUM1Z4y8L2Y0o/a9hFg==","shasum":"16c88c8f597c5c82e1ddcbbd34fa0989592dccd6","tarball":"https://registry.npmjs.org/@centoic/ipeds-fetch/-/ipeds-fetch-0.3.0.tgz","fileCount":56,"unpackedSize":90251,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF/FfWwaljQHHSo5z3+S19g0wJnOnVTvL8auqcDroQIAAiEA9hcIP7NFAyfaGvcP/IMY5cEOYiOQbhNM6EPFCrDQLYk="}]},"_npmUser":{"name":"jasontyping","email":"npm.dev@jasonroth.net"},"directories":{},"maintainers":[{"name":"jasontyping","email":"npm.dev@jasonroth.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ipeds-fetch_0.3.0_1783454261664_0.187071702749795"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-13T01:51:26.731Z","modified":"2026-07-07T19:57:41.948Z","0.1.0":"2026-05-13T01:51:27.053Z","0.2.0":"2026-05-14T22:44:02.957Z","0.2.1":"2026-05-16T19:51:27.657Z","0.3.0":"2026-07-07T19:57:41.804Z"},"bugs":{"url":"https://github.com/centoic/ipeds-fetch/issues"},"license":"MIT","homepage":"https://github.com/centoic/ipeds-fetch#readme","keywords":["ipeds","nces","education","data","cli","download"],"repository":{"type":"git","url":"git+https://github.com/centoic/ipeds-fetch.git"},"description":"CLI tool and library for downloading IPEDS data files","maintainers":[{"name":"jasontyping","email":"npm.dev@jasonroth.net"}],"readme":"<p align=\"center\">\n  <img src=\"assets/ipeds-fetch-logo.png\" width=\"220\" alt=\"IPEDS Fetch mascot — a seated cartoon dog\">\n</p>\n\n# @centoic/ipeds-fetch\n\nA command-line tool and TypeScript library for downloading data files and data dictionaries from the [IPEDS](https://nces.ed.gov/ipeds/) (Integrated Postsecondary Education Data System) Complete Data Files repository maintained by NCES.\n\n## Prerequisites\n\n- **Node.js >= 22**\n- **Playwright browsers**: This tool uses Playwright to interact with the IPEDS ASP.NET WebForms site. Install the Chromium browser before first use:\n\n  ```bash\n  npx playwright install chromium\n  ```\n\n## Quick Start\n\n```bash\nnpx @centoic/ipeds-fetch --years 2024 --tables \"IC*\" --list\n```\n\n## Installation\n\n### Global install\n\n```bash\nnpm install -g @centoic/ipeds-fetch\nipeds-fetch --years 2024 --tables HD2024 --output ./data\n```\n\n### Local install\n\n```bash\nnpm install @centoic/ipeds-fetch\n```\n\n## CLI Usage\n\n```\nipeds-fetch --years <spec> --tables <patterns> [options]\n```\n\n### Required Options\n\n| Option | Description |\n|--------|-------------|\n| `--years <spec>` | Year specification (see below) |\n| `--tables <patterns>` | Table name pattern(s), comma-separated (see below) |\n\n### Optional Options\n\n| Option | Description |\n|--------|-------------|\n| `--list[:format]` | List matching tables instead of downloading. Formats: `text` (default), `json`, `tsv` |\n| `--with-dictionaries[:format]` | Also download data dictionaries (.xlsx/.xls) for each table. Use `:text` to convert .xlsx dictionaries to CSV |\n| `--output <dir>` | Output directory (default: current working directory) |\n| `--delay <ms>` | Delay in milliseconds between consecutive downloads (default: 0) |\n| `--help` | Display help information |\n| `--version` | Display version number |\n\n### Year Specification\n\n| Format | Example | Interpretation |\n|--------|---------|----------------|\n| Single year | `2024` | Just year 2024 |\n| Comma-separated | `2020,2022,2024` | Years 2020, 2022, and 2024 |\n| Range (inclusive) | `2020-2024` | Years 2020 through 2024 |\n| Mixed | `2010,2015-2017,2020` | 2010, 2015, 2016, 2017, 2020 |\n| All years | `all` | All available years (1980-present) |\n\n### Table Patterns\n\nPatterns use glob-style matching with `*` as the wildcard (case-insensitive).\n\n| Pattern | Example | Matches |\n|---------|---------|---------|\n| Exact name | `HD2024` | Only `HD2024` |\n| Wildcard suffix | `IC*` | `IC2024`, `IC2024_AY`, etc. |\n| Wildcard prefix | `*_DIST` | `EF2024A_DIST`, `EFFY2024_DIST`, etc. |\n| Wildcard both | `*2024*` | Any table containing \"2024\" |\n| All tables | `*` | All tables for the selected year(s) |\n| Multiple patterns | `HD*,IC*,ADM*` | Union of all matches |\n\n### Examples\n\n```bash\n# List all institutional characteristics tables for 2024 (human-readable)\nipeds-fetch --years 2024 --tables \"IC*\" --list\n\n# List all tables for 2010 in JSON format\nipeds-fetch --years 2010 --tables \"*\" --list:json\n\n# Download HD2024 with its data dictionary\nipeds-fetch --years 2024 --tables HD2024 --with-dictionaries\n\n# Download HD2024 with its data dictionary, converting .xlsx to CSV\nipeds-fetch --years 2024 --tables HD2024 --with-dictionaries:text\n\n# Download all enrollment tables for 2020-2024 with 500ms delay between downloads\nipeds-fetch --years 2020-2024 --tables \"EF*\" --delay 500 --output ./enrollment-data\n\n# Download specific tables across multiple years\nipeds-fetch --years 2018-2022 --tables \"HD*,IC*\" --with-dictionaries\n\n# Download everything for a single year\nipeds-fetch --years 2024 --tables \"*\" --output ./ipeds-2024\n```\n\n## Library API\n\n```ts\nimport {\n    fetchTablesForYears,\n    filterTablesByPatterns,\n    parseTablePatterns,\n    downloadTables,\n    downloadZipAndExtract,\n    parseYearSpec,\n    type DictionaryFormat,\n} from \"@centoic/ipeds-fetch\";\n```\n\n### `fetchTablesForYears(years: number[]): Promise<TableMetadata[]>`\n\nScrapes the IPEDS Data Files page for the given years and returns a list of available tables.\n\n```ts\nconst tables = await fetchTablesForYears([2024]);\n```\n\n### `parseYearSpec(spec: string): { years: number[]; warnings: string[] }`\n\nParses a year specification string into an array of years.\n\n```ts\nconst { years, warnings } = parseYearSpec(\"2020-2024,2018\");\n// years = [2018, 2020, 2021, 2022, 2023, 2024]\n```\n\n### `parseTablePatterns(spec: string): string[]`\n\nSplits a comma-separated pattern string into individual patterns.\n\n```ts\nconst patterns = parseTablePatterns(\"HD*,IC*\");\n// patterns = [\"HD*\", \"IC*\"]\n```\n\n### `filterTablesByPatterns(tables: TableMetadata[], patterns: string[]): TableMetadata[]`\n\nFilters a list of tables by glob patterns (case-insensitive, `*` wildcard).\n\n```ts\nconst filtered = filterTablesByPatterns(tables, [\"HD2024\", \"IC*\"]);\n```\n\n### `downloadTables(options: DownloadTablesOptions): Promise<number>`\n\nDownloads data files (and optionally dictionaries) for a list of tables. Returns the total number of files saved.\n\n```ts\nconst fileCount = await downloadTables({\n    tables: filtered,\n    outputDir: \"./data\",\n    withDictionaries: true,\n    dictionaryFormat: \"text\",\n    delayMs: 500,\n    onProgress: (msg) => console.log(msg),\n    onWarning: (msg) => console.warn(msg),\n    onItemComplete: (table, result) => {\n        if (!result.success) {\n            console.error(`Failed: ${table.tableName}`);\n        }\n    },\n});\n```\n\n### `downloadZipAndExtract(url: string, outputDir: string): Promise<DownloadZipResult>`\n\nDownloads a single zip file and extracts its contents to the output directory.\n\n### Types\n\n```ts\ninterface TableMetadata {\n    year: number;\n    survey: string;\n    title: string;\n    tableName: string;\n    dataFileUrl: string;\n    dictionaryUrl: string;\n}\n\ninterface DownloadTablesOptions {\n    tables: TableMetadata[];\n    outputDir: string;\n    withDictionaries?: boolean;\n    dictionaryFormat?: \"original\" | \"text\";\n    delayMs?: number;\n    onProgress?: (message: string) => void;\n    onWarning?: (message: string) => void;\n    onItemComplete?: (table: TableMetadata, itemResult: DownloadItemResult) => void;\n    onAllComplete?: (totalFiles: number) => void;\n}\n\ninterface DownloadItemResult {\n    type: \"data\" | \"dictionary\";\n    success: boolean;\n    files: ExtractedFile[];\n    error?: DownloadErrorInfo;\n}\n\ninterface DownloadErrorInfo {\n    message: string;\n    category: \"download\" | \"extraction\" | \"conversion\";\n    url: string;\n    isHttpError: boolean;\n    httpStatus?: number;\n    httpStatusText?: string;\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Type check\npnpm run typecheck\n\n# Lint\npnpm run lint\n\n# Build (compiles src/ to dist/)\npnpm run build\n```\n\n## How It Works\n\nThe IPEDS Data Center uses ASP.NET WebForms with no public API. This tool uses Playwright to automate a headless browser that:\n\n1. Navigates to the IPEDS Data Files page\n2. Selects the requested year from the dropdown\n3. Scrapes the resulting table listing (survey, title, table name, download URLs)\n4. Downloads zip files for matching tables\n5. Extracts CSV data files and XLSX/XLS dictionaries (optionally converting .xlsx to CSV)\n\n## Disclaimer\n\nThis project is not affiliated with, endorsed by, or connected to the National Center for Education Statistics (NCES), the U.S. Department of Education, or any other government entity. All data is sourced from publicly available NCES IPEDS data files.\n\nNothing in this repository constitutes investment advice, a recommendation, or an offer to buy or sell any security. Centoic is a registered investment adviser in California; however, this tool is provided as general-purpose open source software and is not part of any advisory service.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}