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. You can even customize what part of the PSGC data to only include in the generated JSON.

Basic Usage

1. Install this package.

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

2. Use this package either from the command line, or as a Node.js API. See the subsections below for details.

Using the CLI

The sample command below shows how to convert input/psgc.xlsx to output/psgc.json.

psgc-t -i /path/to/input/psgc.xlsx -o /path/to/output/psgc.json

That's it!

Now, if you'd like to check out all available CLI options, run:

psgc-t --help

The help text includes an instruction on how to cherry-pick data you only want to include in the JSON to generate.

API Guide

To use this package as an API, import as follows:

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

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

And then use as such:

import { transcode } from "@c-collamar/psgc-transcoder";

// convert psgc xlsx published from the PSA website into a json file
transcode('/path/to/input/psgc.xlsx', '/path/to/output/psgc.json');

See the complete API reference section for more information.

API Reference

This section is a work-in-progress. In the meantime, feel free to explore the exported goodies this package offers. 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 parse the JSON generated by this transcoder into a PSGC tree, then manually navigate said tree to do stuff. Watch out for it!