Algeria API

A list of Algerian Wilayas, Dairas and Baladyahs.

Features

• Exposes a RESTful API
• GraphQL Endpoint
• JSON Files
  • Postal codes by wilaya results/postal-codes-results.json
  • Wilayas list (with Dairas and Baladiyahs lists) results/WilayaList.json

API Documentation

• Get a list of all Wilayas GET https://localhost:3000/api/v1/wilaya

• Get Wilaya's details: GET https://localhost:3000/api/v1/wilaya/matricule/:matricule, example:

  ~: curl -X GET -i http://localhost:3000/api/v1/wilaya/matricule/31
  
  # Response
  {
    "data": {
      "mattricule": 31,
      "name": "Oran",
      "name_ar": "وهران",
      "name_en": "Oran",
      "phoneCodes": [
        41
      ],
      "postalCodes": [
        31000,
        31001,
        ...
        31117,
        31118
      ],
      "dairats": [
        {
          "name": "AIN TURK",
          "name_ar": "AIN TURK",
          "name_en": "AIN TURK",
          "baladyiats": []
        },
        {
          "name": "ARZEW",
          "name_ar": "ARZEW",
          "name_en": "ARZEW",
          "baladyiats": []
        },
        ...
      ]
    }
  }

• Get the adjacent (nearby wilayas)

  • Only wilaya codes /wilaya/adjacence/:matricule
  • Wilaya names /wilaya/adjacence/:matricule/names example response:

      {
      "data": {
        "names": [
          {
            "mattricule": 46,
            "name": "Ain Temouchent",
            "name_ar": "عين تموشنت",
            "name_en": "Ain Temouchent"
          },
          {
            "mattricule": 22,
            "name": "Sidi Bel Abbes",
            "name_ar": "سيدي بلعباس",
            "name_en": "Sidi Bel Abbes"
          },
          {
            "mattricule": 29,
            "name": "Mascara",
            "name_ar": "معسكر",
            "name_en": "Mascara"
          },
          {
            "mattricule": 27,
            "name": "Mostaganem",
            "name_ar": "مستغانم",
            "name_en": "Mostaganem"
          }
        ],
        "mattricules": [
          46,
          22,
          29,
          27
        ]
      }
    }

  • Short format (only wilaya names in a language and their codes)

      {
        "data": {
          "names": [
            "عين تموشنت",
            "سيدي بلعباس",
            "معسكر",
            "مستغانم"
          ],
          "mattricules": [
            46,
            22,
            29,
            27
          ]
        }
      }

• You can get an XML result by adding a format=xml query parameter, example:

  • GET: http://localhost:3000/api/v1/wilaya/matricule/31?format=xml will return:

  <?xml version="1.0" encoding="UTF-8"?>
  <wilaya>
    <phoneCodes>
      <phoneCode>41</phoneCode>
    </phoneCodes>
    <postalCodes>
      <postalCode>31000</postalCode>
      <postalCode>31001</postalCode>
      ...
      <postalCode>31118</postalCode>
    </postalCodes>
    <adjacentWilayas>
      <adjacentWilaya>46</adjacentWilaya>
      <adjacentWilaya>22</adjacentWilaya>
      <adjacentWilaya>29</adjacentWilaya>
      <adjacentWilaya>27</adjacentWilaya>
    </adjacentWilayas>
    <mattricule>31</mattricule>
    <name>Oran</name>
    <nameAr>وهران</nameAr>
    <nameEn>Oran</nameEn>
    <dairats>
      <dairat>
        <baladyiats>
          <baladyiat>
            <code>3101</code>
            <name>ORAN</name>
            <nameAr>وهران</nameAr>

• Get postal codes by Wilaya

• Get wilaya by postal codes

• Get Wilaya by phone code

  • GET: http://localhost:3000/wilaya/phone-codes?code=41 and for getting XML results http://localhost:3000/wilaya/phone-codes?code=41&format=xml

• Healthcheck

  • GET: http://localhost:3000/healthcheck

Find the full documentation here.

TODOs & Future Improvements/Features

• Add Tamazight Translation
• Build a dashboard to manage/correct data
• Match each postal code withe its provinces
• Add long/latt cordinates
• sqlite ?

Contributing

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with us before making a change. And also, please make sure to read our guidelines for contributing

Improving the API (new features, bug fixes...)

📝 🐳 🌐 🏗️ 🐛 ⚡ 👷 ✨

If you want to work on the API server, just pull this repository then run npm install

To run the development server

npm run server:dev
# or
yarn server:dev

To run in Docker

npm run docker:prod
# Or
yarn docker:prod

Improving the Wilayas List (translations, corrections...)

📝 🌐 🏗️ 🐛 ⚡ 👷 ✨

The wilaya models are auto-generated by crawling and by using the fine work of mohsenuss91/AlgerianAdministrativeDivision. If you want to contribute more by adding, correcting or improving the results... Please create an issue so we can discuss it, and then you just need to update the results on results/WilayaList.json

License

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

Acknowledgments

• mohsenuss91/AlgerianAdministrativeDivision
• AbderrahmeneDZ/Wilaya-Of-Algeria/Wilaya_Of_Algeria.json
• Postal codes and Dairas list are collected by crawling the Algérie Poste and Interior ministry websites, the scripts I used are in tools/