use-postal-ph

This utility library is specifically designed for the Philippines, providing comprehensive information on postal codes, municipalities, locations, and regions. Moreover, searching within the library is case insensitive.

Contents

• Installation
• Usage
• Demo
• Importing Types
• Type Definitions
• Query Options
• ECMAScript Module (ESM) Entry Point
• Contribution Guidelines
• References
• License

Installation

Install via NPM:

npm install use-postal-ph

Or via Yarn:

yarn add use-postal-ph

Usage

To start using the use-postal-ph library, follow these steps:

import usePostalPH from 'use-postal-ph';

You can now utilize the library's methods to retrieve postal code, municipality, location, and region information.

const postalPH = usePostalPH();

// Fetch a list of municipalities
const municipalities = postalPH.fetchMunicipalities();
console.log(municipalities);

// Fetch postal codes
const postalCodes = postalPH.fetchPostCodes();
console.log(postalCodes);

// Fetch locations
const locations = postalPH.fetchLocations();
console.log(locations);

// Fetch regions
const regions = postalPH.fetchRegions();
console.log(regions);

// Fetch all data lists
const dataLimit = postalPH.fetchDataLists();
console.log(dataLimit);

You can also specify search criteria and limit the number of results returned:

// Fetch a list of municipalities starting with 'Manila' and limit the result to 10
const municipalities = postalPH.fetchMunicipalities({search: 'Manila', limit: 10});
console.log(municipalities);

// Fetch postal code for 6045
const postalCodes = postalPH.fetchPostCodes({search: 6045});
console.log(postalCodes);

// Fetch postal codes with a limit of 5
const postalCodesLimit = postalPH.fetchPostCodes({limit: 5});
console.log(postalCodesLimit);

// Fetch locations containing 'Cebu' and limit the result to 3
const locations = postalPH.fetchLocations({search: 'Cebu', limit: 3});
console.log(locations);

// Fetch regions starting with 'NCR' and limit the result to 8
const regions = postalPH.fetchRegions({search: 'NCR', limit: 8});
console.log(regions);

// Fetch all data lists with a limit of 15
const dataLimit = postalPH.fetchDataLists({limit: 15});
console.log(dataLimit);

// Fetch data based on the search criteria
const dataList = postalPH.fetchDataLists({
    post_code: 6045,
    location: "Talisay",
    region: "VII",
    municipality: "Cebu"
});
console.log(dataList);

Demo

Explore the live demo to experience fetching and searching functionalities for municipalities, post codes, locations, and regions. Interact with the application to witness its efficiency and responsiveness in action.

https://use-postal-ph.vercel.app

Importing Types

You can also import specific types provided by use-postal-ph:

import type {PlaceProps, SearchCriteriaProps, PlaceListCriteriaProps} from "use-postal-ph";

Type Definitions

Here are the type definitions provided by use-postal-ph:

export type PlaceDataProps = {
    data: PlaceProps[];
};

export type PlaceProps = {
    municipality?: string;
    location?: string;
    post_code?: number | string;
    region?: string;
};

export type SearchCriteriaProps = {
    search?: number | string;
    limit?: number;
};

export type PlaceListCriteriaProps = PlaceProps & {
    limit?: number;
};

Query Options

When using the library's methods, you have the option to include an object containing parameters for more specific queries:

• search: This parameter is used to find specific information. For postal codes, search directly for the code itself. You can also search for municipalities, locations, and regions based on your query.
• limit: This parameter restricts the number of results returned for municipalities, locations, and regions. However, it does not affect the results when searching for postal codes.
• municipality: Search by the name of the municipality.
• post_code: Search by the postal code.
• location: Search by the specific district or neighborhood.
• region: Search by the region where the place is located.

ECMAScript Module (ESM) Entry Point

If you prefer not to install the package and want to include the ECMAScript module (ESM) entry point directly in your project, you can use the following script tag:

• CDN ( jsDelivr): https://cdn.jsdelivr.net/npm/[email protected]/dist/index.mjs

• NPM: https://unpkg.com/[email protected]/dist/index.mjs

Import Statement:

<script type="module">
    import usePostalPH from 'https://unpkg.com/[email protected]/dist/index.mjs';

    const {
        fetchDataLists,
        fetchLocations,
        fetchMunicipalities,
        fetchPostCodes,
        fetchRegions
    } = usePostalPH();

    console.log(fetchPostCodes({search: "6045"}))
</script>

This script imports the fetchPostCodes function from the use-postal-ph package and retrieves information for the postal code '6045'. It then logs the result to the console.

{
  "location": "Cebu",
  "region": "VII",
  "municipality": "Talisay",
  "post_code": 6045
}

Contribution Guidelines

Contributions are highly appreciated! To contribute, fork the repository, create a new branch for your changes, and submit a pull request. Please ensure your code adheres to the existing coding standards and conventions. While this library provides information, it may not be comprehensive. Contributions aimed at enhancing the comprehensiveness of the data are welcome.

References

The use-postal-ph library utilizes data sourced from Wikipedia, including information on regions, provinces, and municipalities of the Philippines.

• Wikipedia - Regions of the Philippines
• Wikipedia - Provinces of the Philippines
• Wikipedia - List of Cities and Municipalities in the Philippines

License

MIT © blckclov3r