/leblad

A JS library providing a list of Algerian administrative areas with many useful APIs.

Primary LanguageJavaScriptMIT LicenseMIT

Le'Blad

npm first-timers-only codecov Mutation testing badge Known Vulnerabilities CodeQL

All Contributors

A library providing a list of Algerian administrative areas with many useful APIs.

Getting started

Usage

Installation

npm install @dzcode-io/leblad --save

API

getWilayaList(projection?: string[])

Returns a list of Algerian provinces (Wilayas)

Arguments

  • projection: string[] (optional) Array of Wilaya Object attributes to keep.

Examples

const { getWilayaList, getWilayaByZipCode } = require('@dzcode-io/leblad');

const allWilayasDetails = getWilayaList();

// if we only want the wilaya names for example:
const wilayasNames = getWilayaList(['name', 'name_ar', 'name_en']);

getWilayaByZipCode(zipCode: number, projection?: string[])

Returns a wilaya that includes the given zipCode.

Arguments

  • zipCode: number (required) A zip code
  • projection: string[] (optional) Array of Wilaya Object attributes to keep

Examples

const { getWilayaByZipCode } = require('@dzcode-io/leblad');

// To get the wilaya that includes the zip code 1000, We can use getWilayaByZipCode
// This example will return Adrar { name: "Adrar", ...}
const wilaya = getWilayaByZipCode(1000);

// We can also select only attributes that we want, For example select name and mattricule:
const wilayaAttributes = getWilayaByZipCode(1000, ['name', 'mattricule']);

getWilayaByCode(wilayaCode: number, projection?: string[])

Takes a wilaya code (matricule) and returns the matching wilaya

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"
  • projection: string[] (optional) Array of Wilaya Object attributes

Examples

const { getWilayaByCode } = require('@dzcode-io/leblad');

console.log(getWilayaByCode(31)); // will print the wilaya object ({name: "Oran"...})
getAdjacentWilayas(wilayaCode: number)

Takes a wilaya code (matricule) and returns a list of adjacent wilayas codes

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"

Examples

const { getAdjacentWilayas } = require('@dzcode-io/leblad');

console.log(getAdjacentWilayas(31)); // will print [46, 22, 29, 27]

getZipCodesForWilaya(wilayaCode: number)

Takes a wilaya code (matricule) and returns a list of Respective Zip-Codes for that wilaya

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"

Examples

const { getZipCodesForWilaya } = require('@dzcode-io/leblad');

console.log(getZipCodesForWilaya(31)); //returns list of zip codes for wilaya 31

getDairatsForWilaya(wilayaCode: number, projection?: string[])

Takes a wilaya code (matricule) ans returns list of all dairats of that wilaya.

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"
  • projection: string[] (optional) Array of Wilaya Object attributes to keep

Examples

const { getDairatsForWilaya } = require('@dzcode-io/leblad');

console.log(getDairatsForWilaya(3)); //returns list of dairats for wilaya 3

getWilayaByPhoneCode(phoneCode: number, projection?: string[])

Takes a phone code and returns the matching wilaya.

Arguments

  • phoneCode: number | string (required) the Wilaya's "phoneCode"
  • projection: string[] (optional) Array of Wilaya Object attributes to keep

Examples

const { getWilayaByPhoneCode } = require('@dzcode-io/leblad');

console.log(getWilayaByPhoneCode(34)); //will the wilaya object ({name: "Béjaïa"...})

console.log(getWilayaByPhoneCode('34')); //will return the same the wilaya object ({name: "Béjaïa"...})

getWilayaByDairaName(dairaName: String, projection?: string[])

Takes a daira name and returns the matching wilaya.

Arguments

  • dairaName: string (required) the Wilaya's "dairaName" in en|fr|ar
  • projection: string[] (optional) Array of Wilaya Object attributes to keep

Examples

const { getWilayaByDairaName } = require('@dzcode-io/leblad');

console.log(getWilayaByDairaName('OUED RHIOU')); // will print the wilaya object ({name: "Relizane"...})

getBaladyiatsForDaira(dairaName: String)

Takes a daira name and returns the matching baladyiats.

Arguments

  • daira: string (required) the Wilaya's "dairaName" in en|fr|ar

Examples

const { getBaladyiatsForDaira } = require('@dzcode-io/leblad');

console.log(getBaladyiatsForDaira('ORAN')); // will return baladyiats for daira of "Oran"

getBaladyiatsForDairaCode(dairaCode: Number)

Takes a daira code and returns the matching baladyiats.

Arguments

  • daira: number (required) the Wilaya's "dairaCode" in en|fr|ar

Examples

const { getBaladyiatsForDairaCode } = require('@dzcode-io/leblad');

console.log(getBaladyiatsForDairaCode(31)); // will return baladyiats for daira of "Oran"

getPhoneCodesForWilaya(wilayaCode: number)

Takes a wilaya code (matricule) and returns a list of phone codes for given wilaya

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"

Examples

const { getPhoneCodesForWilaya } = require('@dzcode-io/leblad');

console.log(getPhoneCodesForWilaya(31)); //returns list of phone codes for wilaya 31

getPhoneCodeForWilaya(wilayaCode: number)

Takes a wilaya code (matricule) and returns the first phone code from a list of phone codes for given wilaya

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"

Examples

const { getPhoneCodeForWilaya } = require('@dzcode-io/leblad');

console.log(getPhoneCodeForWilaya(16)); //returns first phone code for wilaya 16

getBaladyiatsForWilaya(wilayaCode: number, projection?: string[])

Takes a wilaya code (mattricule) and returns array of Baladiyates of wilaya.

Arguments

  • wilayaCode: number (required) the Wilaya's "matricule"
  • projection: string[] (optional) Array of Baladyia Object attributes

Examples

const { getBaladyiatsForWilaya } = require('@dzcode-io/leblad');

console.log(getBaladyiatsForWilaya(31)); // will print the baladyiats list ([{ code: 3125, name: 'AIN KERMA'..},{ code: 3105,name: 'ES SENIA',}])

getWilayaByBaladyiaName(baladyiaName: number, projection?: string[])

Takes a Baladyia name and returns wilaya in which baladyia is located.

Arguments

  • baladyiaName: number (required) the Baladyia name
  • projection: string[] (optional) Array of Wilaya Object attributes

Examples

const { getWilayaByBaladyiaName } = require('@dzcode-io/leblad');

console.log(getWilayaByBaladyiaName('ES SENIA')); // will print the wilaya object ({name: "Oran"...})

getDairaByBaladyiaName(baladyiaName: number, projection?: string[])

Takes a Baladyia name and returns daira in which baladyia is located.

Arguments

  • baladyiaName: number (required) the Baladyia name
  • projection: string[] (optional) Array of Wilaya Object attributes

Examples

const { getDairaByBaladyiaName } = require('@dzcode-io/leblad');

console.log(getDairaByBaladyiaName('ES SENIA')); // will print the daira object ({name: "ES SENIA"...})

Helper methods

projectObject(data: (object|array), projection?: string[])

Return an object or an array of object with only data (example: Wilaya, Daira, Baladiya) attribute you select in the projection attributes array.

Arguments

  • data: (object|array) (required) A data object or an array of data objects(Wilayas, Dairas, Baladiyas)
  • projection: string[] (optional) Array of data Object attributes

Examples

const { projectObject: projectWilaya } = require('@dzcode-io/leblad').utils;

...

const wilayasNames = projectWilaya(someWilayaObject, ['name', 'name_ar', 'name_en']);

isValidWilayaCode(code:number)

Check if a given wilaya code (matricule) is valid (i.e is an integer between 1 and 48).

Arguments

  • code: number (required) Wilaya code

isValidZipCode(code:(number|string))

Check if a given zip code is valid (i.e is an integer between 1000 and 48073).

Arguments

  • code: (number|string) (required) zip code

Local development

Perquisites

Make sure you have:

Install the dependencies

npm install

Update the Wilayas dataset

npm run update-dataset

Testing

Simply run

npm test

Or this command for the watch mode:

npm run test.watch

You can also run mutation tests (using Stryker-mutator)

npm run test.mutation

Contributors ✨

Thanks goes to these wonderful people (emoji key):


Fortas Abdeldjalil

🚧 💻 👀

Zakaria Mansouri

🔧 👀

Oussama Bouchikhi

💻

Nasser Abachi

💻

Anurag sati

💻

HamdiAmine

💻

xxKeefer

💻

Joey Nguyen

💻

LOUKIL Mohamed Reda

🤔 💻

Fortas Oussama Ilyes

💻

Abdelmounaim TAZI

💻

Toumi abderrahmane

💻 💡

This project follows the all-contributors specification. Contributions of any kind welcome!

Contributing

When contributing to this repository, please first discuss the change you wish to make by opening an issue, sending an e-mail, or any other method with us before making a change.

And also, please make sure to read our guidelines for contributing.

Similar projects

  • dz-communes An NPM package exposing a list of all of the 48 wilayas of Algeria and their communes.
  • algeria-api An web API exposing Wilayas data. We data from that project as a source of truth for (data/WilayaList.json)

License

This project is licensed under the MIT License - see the LICENSE file for details