{"id":17371829,"url":"https://github.com/fityannugroho/idn-area-data","last_synced_at":"2025-04-06T10:09:38.429Z","repository":{"id":172740523,"uuid":"649514821","full_name":"fityannugroho/idn-area-data","owner":"fityannugroho","description":"Provides the administrative areas data of Indonesia based on the latest official sources 🇮🇩","archived":false,"fork":false,"pushed_at":"2025-03-21T03:58:00.000Z","size":5260,"stargazers_count":57,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-30T09:05:19.972Z","etag":null,"topics":["data","data-sources","hacktoberfest","idn-area","indonesia","island","javascript","open-data","pulau","wilayah","wilayah-indonesia"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/idn-area-data","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fityannugroho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["fityannugroho"],"patreon":null,"open_collective":null,"ko_fi":"fityannugroho","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":["https://trakteer.id/fityannugroho/tip","https://saweria.co/fityannugroho"]}},"created_at":"2023-06-05T03:34:24.000Z","updated_at":"2025-03-21T03:58:03.000Z","dependencies_parsed_at":"2024-01-16T07:31:14.546Z","dependency_job_id":"f9d566b9-02c1-4717-bf1a-eeda8785094f","html_url":"https://github.com/fityannugroho/idn-area-data","commit_stats":{"total_commits":228,"total_committers":2,"mean_commits":114.0,"dds":"0.23245614035087714","last_synced_commit":"85ff09277ad4ac19c7eb829b33375574b941276c"},"previous_names":["fityannugroho/idn-area-data"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fityannugroho%2Fidn-area-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fityannugroho%2Fidn-area-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fityannugroho%2Fidn-area-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fityannugroho%2Fidn-area-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fityannugroho","download_url":"https://codeload.github.com/fityannugroho/idn-area-data/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464185,"owners_count":20942966,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data","data-sources","hacktoberfest","idn-area","indonesia","island","javascript","open-data","pulau","wilayah","wilayah-indonesia"],"created_at":"2024-10-16T01:05:43.181Z","updated_at":"2025-04-06T10:09:38.403Z","avatar_url":"https://github.com/fityannugroho.png","language":"TypeScript","funding_links":["https://github.com/sponsors/fityannugroho","https://ko-fi.com/fityannugroho","https://trakteer.id/fityannugroho/tip","https://saweria.co/fityannugroho"],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"\"\u003eIndonesian Area Data (\u003ci\u003eData Wilayah Indonesia\u003c/i\u003e)\u003c/h1\u003e\n\nProvides the administrative areas data of Indonesia (province, regency, district, village, and island) based on the latest official sources.\n\n[![npm version](https://img.shields.io/npm/v/idn-area-data.svg)](https://www.npmjs.com/package/idn-area-data)\n[![npm downloads](https://img.shields.io/npm/dm/idn-area-data.svg)](https://www.npmjs.com/package/idn-area-data)\n[![GitHub license](https://img.shields.io/github/license/fityannugroho/idn-area-data.svg)](LICENSE)\n[![install size](https://packagephobia.com/badge?p=idn-area-data)](https://packagephobia.com/result?p=idn-area-data)\n\n## Prerequisite\n\n- [Node.js](https://nodejs.org) (version 18 or higher)\n- [npm 9](https://www.npmjs.com) or [yarn](https://yarnpkg.com)\n\n## Upgrading\n\nIf you are upgrading from version 2 to version 3, please read the [upgrade guide](docs/upgrading/upgrade-to-v3.md).\n\n## Installation\n\nYou can install this package via [npm](https://www.npmjs.com), [yarn](https://yarnpkg.com), or [pnpm](https://pnpm.io) (pnpm is recommended).\n\n```pnpm\npnpm add idn-area-data\n```\n\n```bash\nnpm install --save idn-area-data\n```\n\n```bash\nyarn add idn-area-data\n```\n\n## Usage\n\nImport the package into your project as shown below.\n\n\u003e [!NOTE]\n\u003e The following code examples use [top level await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await) to run the asynchronous function. You also can use [IIFE](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), [`.then()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then), or run it inside anonther `async` function instead.\n\n### ESM\n\nImport specific function only :\n\n```js\nimport { getProvinces } from 'idn-area-data';\n\nconst provinces = await getProvinces();\n```\n\nImport the entire module :\n\n```js\nimport * as IdnArea from 'idn-area-data';\n\nconst provinces = await IdnArea.getProvinces();\n```\n\n### CommonJS\n\nSince version 3.0.0, **idn-area-data** is published as ECMAScript Module (ESM). So that, for CommonJS user, you need to import it using [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) like this :\n\n```js\nconst { getProvinces } = await import('idn-area-data');\nconst provinces = await getProvinces();\n```\n\nThen, you can get the data you need using these methods below.\n\n## Methods\n\n### `getProvinces()`\n\nAsynchronous function to get all provinces data.\n\n```js\nimport { getProvinces } from 'idn-area-data';\n\nconst provinces = await getProvinces();\nconsole.log(provinces);\n/*\n[\n  {\n    code: '11',\n    name: 'ACEH',\n  },\n  ...\n]\n*/\n```\n\n### `getRegencies(?options)`\n\nAsynchronous function to get all regencies data\n\n```js\nimport { getRegencies } from 'idn-area-data';\n\nconst regencies = await getRegencies();\nconsole.log(regencies);\n/*\n[\n  {\n    code: '11.01',\n    name: 'KABUPATEN ACEH SELATAN',\n    province_code: '11',\n  },\n  ...\n]\n*/\n```\n\nIf **`options.transform`** argument is `true`, the property naming will be changed from `snake_case` into **`camelCase`**.\n\n```js\nconst regencies = await getRegencies({ transform: true });\n/*\n[\n  {\n    code: '11.01',\n    name: 'KABUPATEN ACEH SELATAN',\n    provinceCode: '11',\n  },\n  ...\n]\n*/\n```\n\n### `getDistricts(?options)`\n\nAsynchronous function to get all districts data.\n\n```js\nimport { getDistricts } from 'idn-area-data';\n\nconst districts = await getDistricts();\nconsole.log(districts);\n/*\n[\n  {\n    code: '11.01.01',\n    name: 'Bakongan',\n    regency_code: '11.01',\n  },\n  ...\n]\n*/\n```\n\nIf **`options.transform`** argument is `true`, the property naming will be changed from `snake_case` into **`camelCase`**.\n\n```js\nconst districts = await getDistricts({ transform: true });\n/*\n[\n  {\n    code: '11.01.01',\n    name: 'Bakongan',\n    regencyCode: '11.01',\n  },\n  ...\n]\n*/\n```\n\n### `getVillages(?options)`\n\nAsynchronous function to get all villages data.\n\n```js\nimport { getVillages } from 'idn-area-data';\n\nconst villages = await getVillages();\nconsole.log(villages);\n/*\n[\n  {\n    code: '11.01.01.2001',\n    district_code: '11.01.01',\n    name: 'Keude Bakongan',\n  },\n  ...\n]\n*/\n```\n\nIf **`options.transform`** argument is `true`, the property naming will be changed from `snake_case` into **`camelCase`**.\n\n```js\nconst villages = await getVillages({ transform: true });\n/*\n[\n  {\n    code: '11.01.01.2001',\n    districtCode: '11.01.01',\n    name: 'Keude Bakongan',\n  },\n  ...\n]\n*/\n```\n\n### `getIslands(?options)`\n\nAsynchronous function to get all islands data.\n\n```js\nimport { getIslands } from 'idn-area-data';\n\nconst islands = await getIslands();\nconsole.log(islands);\n/*\n[\n  {\n    code: '11.01.40001',\n    coordinate: '03°19'03.44\" N 097°07'41.73\" E',\n    name: 'Pulau Batukapal',\n    is_outermost_small: '0',\n    is_populated: '0',\n    regency_code: '11.01',\n  },\n  ...\n]\n*/\n```\n\nIf **`options.transform`** argument is `true`, the property naming will be changed from `snake_case` into **`camelCase`** and the data type will be converted (for `boolean` and `number`).\n\n\u003e [!IMPORTANT]\n\u003e The `regencyCode` will be **`null`** if the island doesn't belong to any regency and the `transform` option is enabled.\n\n```js\nconst islands = await getIslands({ transform: true });\n/*\n[\n  {\n    code: '11.01.40001',\n    coordinate: '03°19'03.44\" N 097°07'41.73\" E',\n    name: 'Pulau Batukapal',\n    isOutermostSmall: false,\n    isPopulated: false,\n    regencyCode: '11.01', \u003c-- It will be `null` if the island doesn't belong to any regency\n  },\n  ...\n]\n*/\n```\n\n### `getData(area, ?options)`\n\nIf you need to **customize the attribute names or values of the data** yourself, you can use this asyncronous function and provide the data transformer configuration in `options.transform`.\n\nTo customize the attribute names, define the pair between the old attribute and the new attribute in `options.transform.headers`. The old attributes is equals to the CSV headers of each [data](#data).\n\nTo customize the attribute values, set the value transformer functions in `options.transform.values`.\n\nSee the example below :\n\n```ts\n// .ts\nimport { getData } from 'idn-area-data';\n\n// Define the custom type of the data\ntype Provinsi = {\n  kode: number;\n  nama: string;\n};\n\n// Get the data\nconst data = await getData\u003cProvinsi\u003e('provinces', {\n  transform: {\n    headers: {\n      code: 'kode',\n      name: 'nama',\n    },\n    values: {\n      code: (value) =\u003e parseInt(value),\n    },\n  },\n});\n\nconsole.log(data);\n/*\n[\n  {\n    kode: 11,\n    nama: 'ACEH',\n  },\n  ...\n]\n*/\n```\n\n```js\n// .js\nimport { getData } from 'idn-area-data';\n\nconst data = await getData('provinces', {\n  transform: {\n    headers: {\n      code: 'kode',\n      name: 'nama',\n    },\n    values: {\n      code: (value) =\u003e parseInt(value),\n    },\n  },\n});\n```\n\n## Try it now\n\nYou can try to run this package in the code playground :\n\n[![Edit idn-area-data](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/p/sandbox/idn-area-data-rkievt)\n\n## Motivation\n\nThis package is a solution that addresses the limitations of other existing packages, repositories, or sources that provides Indonesian area data. Here's why it's the perfect choice for developers :\n\n1. Up-to-date and Government-Sourced Data\n\n   This package ensures that you have access to the most current Indonesian area data. We rely on official government sources, guaranteeing that the information provided is reliable and up-to-date.\n\n1. Seamless Database Integration\n\n   This package offers data in a format that seamlessly integrates with various databases. Unlike other sources that provide data solely in SQL query or JSON, this package store the data sources in CSV and use JavaScript to parse it into an array. You can easily insert the data into any database by using database integration tools like [Prisma](https://www.prisma.io), [Sequelize](https://sequelize.org), [node-postgres](https://node-postgres.com), [mongodb](https://github.com/mongodb/node-mongodb-native), etc. This approach ensures compatibility with a wide range of databases.\n\n1. Easy Integration and Minimum Package Size\n\n   You just need to install this package as a dependency into your project, just like any other library or module. This package has minimal dependencies on other packages, with the majority of its size being attributed to the data source itself.\n\n## Data\n\nThe data we used is based on official data from the government and stored in separated CSV files by the levels in [`data`](data) directory.\n\n\u003e You can see the list of official sources we refer to [here](docs/references.md).\n\n## Problem Reporting\n\nWe have different channels for each problem, please use them by following these conditions :\n\n### Reporting a Bug\n\nTo report a bug, please open a new issue following the guide [here](CONTRIBUTING.md#submitting-an-issue).\n\n### Requesting a New Feature\n\nIf you have a new feature in mind, please open a new issue following the guide [here](CONTRIBUTING.md#submitting-an-issue).\n\n### Asking a Question\n\nIf you have a question, you can search for answers in the GitHub Discussions Q\u0026A category [here](https://github.com/fityannugroho/idn-area-data/discussions/categories/q-a). If you don't find a relevant discussion already, you can open a new discussion.\n\n## License\n\n- This package and repository are licensed under the [MIT License](LICENSE).\n- All data that included in this package and repository are made available under the [Open Database License](data/LICENSE.md).\n\nThese licenses apply to the current and previous versions, and apply to future versions until changed.\n\n## Support This Project\n\n**Give a ⭐️** if this project helped you!\n\nAlso please consider supporting this project by **becoming a sponsor**. Your donation will help us to maintain and develop this project and provide you with better support.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffityannugroho%2Fidn-area-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffityannugroho%2Fidn-area-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffityannugroho%2Fidn-area-data/lists"}