ph-municipalities have NPM scripts that allow interactive querying of Philippines municipalities included in one or more provinces or from a whole region, with an option of writing them to JSON files from the command line.
It uses /data/day1.xlsx
(downloaded and stored as of this 20220808) from PAGASA's 10-day weather forecast excel files as the default data source.
It also asks users to key in the download URL of a remote PAGASA 10-Day weather forecast excel file should they want to use another excel file for a new and updated data source.
Extracted municipalities are written in JSON files following the format:
{
"metadata": {
"source": "https://pubfiles.pagasa.dost.gov.ph/pagasaweb/files/climate/tendayweatheroutlook/day1.xlsx",
"title": "List of PH Municipalities By Province and Region",
"description": "This dataset generated with reference to the excel file contents from the source URL on 20220808.",
"date_created": "Mon Aug 08 2022"
},
"data": {
"Albay": ["Bacacay", "Camalig", ... ],
"Camarines Norte": ["Basud", "Capalonga", ... ],
"Camarines Sur": ["Baao", "Balatan", ... ],
...
}
}
Pre-compiled windows binaries are available for download in the latest Releases download page.
The following dependencies are used for this project. Feel free to use other dependency versions as needed.
- Windows 10 OS
- nvm for Windows v1.1.9
- NodeJS, installed using nvm
- node v16.14.2
- npm v8.5.0
- Excel file
- ph-municipalities uses Excel files in the
/data
directory as data source. - At minimum, the excel file should have a column that contains municipality and province names following the pattern
"municipalityName (provinceName)"
- Checkout the excel file format on the
/data/day1.xlsx
sample file for more information
- ph-municipalities uses Excel files in the
- (Optional) Download URL for a remote excel file.
- See the
EXCEL_FILE_URL
variable on the Installation section.
- See the
- ph-municipalities
- Requirements
- Contents
- Installation
- Available Scripts
- Class Usage
- Building Standalone Windows Executables
- Compiling into Single, Minified Files
-
Clone this repository.
git clone https://github.com/ciatph/municipalities-by-province.git
-
Install dependencies.
npm install
-
Create a
.env
file from the.env.example
file. Use the default values for the following environment variables.Variable Name Description EXCEL_FILE_URL (Optional) Remote excel file's download URL.
If provided, the excel file will be downloaded and saved on the specifiedpathToFile
local filesystem location during theExcelFile
class initialization.
Read on Usage for more information.SHEETJS_COLUMN Column name read by sheetjs in an excel file.
This column contains the municipality and province names following the string pattern"municipalityName (provinceName)"
Default value is__EMPTY
SORT_ALPHABETICAL Arranges the municipality names in alphabetical order.
Default value is1
. Set to0
to use the ordering as read from the Excel file.SPECIAL_CHARACTERS Key-value pairs of special characters or garbled text and their normalized text conversions, delimited by the ":"
character.
Multiple key-value pairs are delimited by the","
character.
If a special character key's value is a an empty string, write it as i.e.,:"some-garbled-text:"
- Asks users to enter the download URL of a remote excel file or use the default local excel file
- Loads and parses the local excel file in
/data/day1.xlsx
by default. - Loads and parses the downloaded excel file in
/data/datasource.xlsx
if download URL in the class constructor is provided.
- Loads and parses the local excel file in
- Displays a list of available PH region names.
- Lists all provinces and municipalities of a specified region via commandline input.
- Asks for an option to write results to a JSON file.
- Run the script as follows if installed using
npm i ph-municipalities
:node .\node_modules\ph-municipalities\src\scripts\by_region.js
- Asks users to enter the download URL of a remote excel file or use the default local excel file
- Loads and parses the local excel file in
/data/day1.xlsx
by default. - Loads and parses the downloaded excel file in
/data/datasource.xlsx
if download URL in the class constructor is provided.
- Loads and parses the local excel file in
- Lists all municipalities under specified province(s) via commandline input.
- Asks for an option to write results to a JSON file.
- Run the script as follows if installed using
npm i ph-municipalities
:node .\node_modules\ph-municipalities\src\scripts\by_province.js
- Downloads and parses a remote excel file.
- Demonstrates sample usage with
await
- Package the Node.js project's
npm start
script into a stand-alone windowsnode16-win-x64
executable. - The windows executable file will be stored in
/dist/ph-regions-win.exe
. Click the executable file to run.
- Package the Node.js project's
npm list:province
script into a stand-alone windowsnode16-win-x64
executable. - The windows executable file will be stored in
/dist/ph-provinces-win.exe
. Click the executable file to run.
- Package the Node.js project's
npm start
andnpm list:province
script into a stand-alone windowsnode16-win-x64
executables in one go. - Each window executable file will be stored in the
/dist
directory.
- Compiles the Node.js project's
npm list:region
script and dependencies into a single script using ncc. - The compiled/minified file will be stored in
/dist/region
. Run the command to use the compiled script:
node dist/region
- Compiles the Node.js project's
npm list:province
script and dependencies into a single script using ncc. - The compiled/minified file will be stored in
/dist/province
. Run the command to use the compiled script:
node dist/province
- Run the
npm list:region
andnpm list:province
scripts in one go. - Each compiled/minified files will be stored in the
/dist
directory.
Lint JavaScript source codes.
Fix JavaScript lint errors.
Below is a simple usage example of the ExcelFile
class. Check out /src/scripts/sample_usage.js
for more examples.
const path = require('path')
const ExcelFile = require('./classes/excel')
// Use the the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')
// Reads an existing excel file on /data/day1.xlsx
file = new ExcelFile({
pathToFile: path.join(__dirname, 'data', 'day1.xlsx'),
// fastload: false
})
// Call init() if fastload=false
// file.init()
// listMunicipalities() lists all municipalities
// for each province
const provinces = ['Albay','Masbate','Sorsogon']
const municipalitiesFromProvince = file.listMunicipalities(provinces)
// writeMunicipalities() writes municipalities data to a JSON file
// and returns the JSON object
const json = file.writeMunicipalities({
provinces,
fileName: path.join(__dirname, 'municipalities.json'),
prettify: true
})
// shapeJsonData() returns the output of writeMunicipalities()
// without writing to a JSON file
const json2 = file.shapeJsonData(provinces)
// JSON data of the parsed excel file will is accessible on
// file.datalist
console.log(file.datalist)
// Set the contents of file.datalist
file.datalist = [
{ municipality: 'Tayum', province: 'Abra' },
{ municipality: 'Bucay', province: 'Abra' }]
Adding a url
field in the constructor parameter will download a remote excel file for data source.
require('dotenv').config()
const path = require('path')
const ExcelFile = require('./classes/excel')
// Use the the following if installed via npm
// const { ExcelFile } = require('ph-municipalities')
const main = async () => {
// Excel file will be downloaded to /data/day1.xlsx
file = new ExcelFile({
pathToFile: path.join(__dirname, 'data', 'day1.xlsx'),
url: process.env.EXCEL_FILE_URL
})
try {
await file.init()
console.log(file.datalist)
} catch (err) {
console.log(err.message)
}
}
main()
Initialize an ExcelFile
class instance.
require('dotenv').config()
const path = require('path')
const { ExcelFile } = require('./classes/excel')
const PHExcel = new ExcelFile({
pathToFile: path.join(path.join(__dirname, '..', '..', 'data', 'day1.xlsx')),
url: process.env.EXCEL_FILE_URL
})
PHExcel.init()
module.exports = PHExcel
Listen to the instance's EVENTS.LOADED
event.
PHExcel.events.on(PHExcel.EVENTS.LOADED, async () => {
console.log('Excel data loaded!')
})
The main npm scripts can be packaged into standalone windows executables. Pre-compiled windows binaries are available for download in the latest Releases download page.
- Run any of the following scripts to build the programs.
npm run build:win:region npm run build:win:province # npm run build:win:all
- Click the resulting executable files in the
/dist
directory to execute.
The main npm scripts can be compiled into standalone JavaScript files together with all its dependencies.
- Run any of the following scripts to compile the source codes.
npm run minify:region npm run minify:province # npm run minify:all
- Run the compiled source codes in the
/dist
directory to execute.node dist/region node dist/province
@ciatph
20220807