psgc-areas/README.md

Provides the full Philippine Standard Geographic Code (PSGC) dataset in JSON with multiple formats (hierarchy, flat list of all areas, regions, provinces, cities, municipalities, municipal districts, and barangays).

# PSGC Areas

## Overview

This package provides an interface to access the Philippine Standard Geographic Code (PSGC) data. The PSGC is a systematic classification and coding of geographic areas in the Philippines, essential for various government and private sector activities such as statistical analysis, geographic information systems (GIS), and more.

## Features

- Retrieve PSGC codes and descriptions.
- Access hierarchical and flat list representations of geographic areas.
- Efficient and easy-to-use API for integrating PSGC data into applications.

## Installation

To install the package, use `npm` or your package manager of choice (e.g., `pnpm`):

```bash
npm install psgc-areas
```

## Usage

### Importing the Package

First, import the package into your project:

```javascript
import { PSGCResource } from "psgc-areas";
```

### Getting All Areas in Hierarchical Representation

To retrieve a hierarchical representation of all areas with regions at the top:

```javascript
PSGCResource.getAll()
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error("Error fetching hierarchical data:", error);
  });
```

### Getting a Flat List of All Areas

To get a flat list of all areas from the PSGC publication:

```javascript
PSGCResource.getAreas()
  .then(areas => {
    console.log(areas);
  })
  .catch(error => {
    console.error("Error fetching areas:", error);
  });
```

### Getting All Regions

To retrieve all regions:

```javascript
PSGCResource.getRegions()
  .then(regions => {
    console.log(regions);
  })
  .catch(error => {
    console.error("Error fetching regions:", error);
  });
```

### Getting All Provinces

To retrieve all provinces:

```javascript
PSGCResource.getProvinces()
  .then(provinces => {
    console.log(provinces);
  })
  .catch(error => {
    console.error("Error fetching provinces:", error);
  });
```

### Getting All Cities

To retrieve all cities:

```javascript
PSGCResource.getCities()
  .then(cities => {
    console.log(cities);
  })
  .catch(error => {
    console.error("Error fetching cities:", error);
  });
```

### Getting All Municipalities

To retrieve all municipalities:

```javascript
PSGCResource.getMunicipalities()
  .then(municipalities => {
    console.log(municipalities);
  })
  .catch(error => {
    console.error("Error fetching municipalities:", error);
  });
```

### Getting All Municipal Districts

To retrieve all municipal districts:

```javascript
PSGCResource.getMunicipalDistricts()
  .then(municipalDistricts => {
    console.log(municipalDistricts);
  })
  .catch(error => {
    console.error("Error fetching municipal districts:", error);
  });
```

### Getting All Barangays

To retrieve all barangays:

```javascript
PSGCResource.getBarangays()
  .then(barangays => {
    console.log(barangays);
  })
  .catch(error => {
    console.error("Error fetching barangays:", error);
  });
```

## API Documentation

### Methods

#### `getAll()`

- **Description:** Fetches a hierarchical representation of all areas with regions at the top.
- **Returns:** A promise that resolves to a hierarchical structure of geographic areas.

#### `getAreas()`

- **Description:** Fetches a flat list of all areas from the PSGC publication.
- **Returns:** A promise that resolves to an array of area objects.

#### `getRegions()`

- **Description:** Fetches all regions.
- **Returns:** A promise that resolves to an array of region objects.

#### `getProvinces()`

- **Description:** Fetches all provinces.
- **Returns:** A promise that resolves to an array of province objects.

#### `getCities()`

- **Description:** Fetches all cities.
- **Returns:** A promise that resolves to an array of city objects.

#### `getMunicipalities()`

- **Description:** Fetches all municipalities.
- **Returns:** A promise that resolves to an array of municipality objects.

#### `getMunicipalDistricts()`

- **Description:** Fetches all municipal districts.
- **Returns:** A promise that resolves to an array of municipal district objects.

#### `getBarangays()`

- **Description:** Fetches all barangays.
- **Returns:** A promise that resolves to an array of barangay objects.

## Contributing

If you would like to contribute, please fork the repository and submit a pull request.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.

## Contact

For questions or suggestions, please open an issue on GitHub.