Update: Since version 2, this package now works directly with the PSGC .xlsx document! 🎉

You no longer have to extract PSGC Excel sheet data into a .csv yourselves (which, by the way, will most likely get you into runtime errors if not done in a particular, undocumented way).

PSGC Transcoder

Convert PSGC data from Excel to programmer-friendly JSON yourselves! You can even customize what part of the PSGC data to only include in the generated JSON.

CLI Quickstart

1. Install this package.

   npm i -g @c-collamar/psgc-transcoder

2. Download any PSGC Excel document published by the Philippine Statistics Authority which you want to convert into accessible JSON.

   Any recent versions of the PSGC document should work fine, like the PSGC-2Q-2021-Publication-Datafile-01092021.xlsx (direct download) which is used in the development of this package.

3. Convert that Excel document to JSON by running:

   psgc-t -i ./PSGC-2Q-2021-Publication-Datafile-01092021.xlsx -o ./psgc.json

   Replace the -i argument with the file path to your downloaded PSGC Excel document, run the command above, and there you have it! You should have a new psgc.json file in your current working directory.

API Quickstart

In addition to its CLI, this package can also be imported into your scripts!

After installing this package, import it as follows:

// import into your ES module
import { transcode } from "@c-collamar/psgc-transcoder"

// or import into your CommonJS module
const { transcode } = require("@c-collamar/psgc-transcoder");

And then use like so:

// equivalent to CLI command: psgc-t -i ./psgc.xlsx -o ./psgc.json
transcode('./psgc.xlsx', './psgc.json');

Viola!

Now the transcode function is cool, but there's actually more functionality baked into this package's API. See the API Reference section for more information.

CLI Options

• --input, -i (required)

  Input filepath. Specify the filepath to an existing PSGC Excel document that you want to transcode.

• --output, -o (required)

  Output filepath. Specify the filepath to the JSON that will be generated, including the filename appended by the .json extension.

• --include, -a (optional)

  Includes. Explicitly specify which PSGC properties to only include in the generated JSON, separated by spaces. By default, all PSGC properties are included.

  See the help text below to know what PSGC properties are allowed to be specified. Also note that the code PSGC property will be included regarless if you omit it from this option.

• --help, -h

  Help text. Display all available CLI options, along with few examples for your reference.

  Usage: psgc-t -i <filepath> -o <filepath>
  
  Options:
      --version  Show version number                                   [boolean]
  -h             Learn how to transpile PSGC to JSON.                  [boolean]
  -i, --input    Path to the input PSGC XLSX.                [string]  [required]
  -o, --output   Path to output the generated PSGC JSON.     [string]  [required]
  -a, --include  Space-separated PSGC fields to include in the output. [array]
                 [choices: "code", "name", "level", "old_name", "class", "income", "type", "population"]
                 [default: ["code", "name", "level", "old_name", "class", "income", "type", "population"]]
  
  Examples:
  psgc-t -i ./psgc.xlsx -o ./psgc.json                 Read PSGC XLSX, output PSGC JSON.
  psgc-t -i ./psgc.xlsx -o ./psgc.json -a name level   Only include "code", "name" and "level" PSGC properties in the generated JSON.

• --version

  Version number. Display the version number of this package.

API Reference

This section is a work in progress. In the meantime, feel free to explore the exported goodies this package offers yourselves, with the aid of your favorite code editors. I made this package with love, so it's well-documented, and is type-strict. Hope you like it! ❤

Motivation

I wanted to use the Philippine Standard Geographic Code (PSGC) standard for one of my projects. The problem was that the PSGC is only being officially issued as an .xlsx document. This means bad news for programmers, because there's no direct way to pull PSGC data out of Excel and into the Node.js environment.

I looked into existing PSGC implementations for Node. Unfortunately, I don't find any of them good enough. Some are barely being maintained. Others have outdated PSGC data. Not to mention they are figgin' heavy!

So, in an effort to make PSGC easier to work with, I made this tool. I exhanged emails with the PSA to make sure my implementation closely matches the standard.

This transcoder is just one of three things I'm working on to make PSGC easier to integrate with; not only into my projects, but yours as well.

Another package I'm working on is a PSGC reader, that will read the JSON file generated by this transcoder, and will give you the productivity you need to actually just with PSGC directly; all one nice API. It's going to save us the pain from us having to manually transcode, parse the transcoding, and navigate the parsed object. Watch out for it!