persiantools

README

Go Persian Tools

An anthology of tools for working with Persian (Iranian) data in Go.

---

Features

Package	What it does
bank	Validate card numbers (Luhn), resolve the issuing bank, and validate Sheba (IBAN) codes with bank details.
bill	Determine a utility bill's type, amount and barcode, and validate its id.
digit	Add/remove thousands separators and convert digits to Persian words.
nationalid	Validate national numbers (code-e Melli) and resolve the issuing city/province.
phonenumbers	Validate Iranian mobile numbers, normalize prefixes and resolve operator details.

Install

go get github.com/amiranmanesh/go-persian-tools@latest

Requires Go 1.23+. Import only the sub-packages you need.

Usage

bank

import "github.com/amiranmanesh/go-persian-tools/bank"

// Card number -> bank slug
name, err := bank.CardInfo("6037701689095443") // "keshavarzi", nil
_, err = bank.CardInfo("6219861034529008")      // "", bank.ErrInvalidCard

// Sheba (IBAN)
sheba := bank.ShebaCode{Code: "IR820540102680020817909002"}
if ok := sheba.IsValid(); ok {
    info := sheba.IsSheba()
    fmt.Println(info.Name)        // Parsian Bank
    fmt.Println(info.PersianName) // بانک پارسیان
}

IsSheba returns a bank.ShebaResult:

type ShebaResult struct {
    Name                   string
    Code                   string
    NickName               string
    PersianName            string
    AccountNumber          string
    AccountNumberAvailable bool
    FormattedAccountNumber string
    Process                func(str string) ShebaProcess
}

bill

import "github.com/amiranmanesh/go-persian-tools/bill"

params := bill.BillParams{BillId: 1117753200140, PaymentId: 12070160}

bill.GetBillType(params)  // "تلفن ثابت"
bill.GetCurrency(params)  // 120000
bill.GetBarCode(params)   // "111775320014000012070160"
bill.VerifyBillID(params) // true

digit

import "github.com/amiranmanesh/go-persian-tools/digit"

digit.DigitToWord("۱۵۶۷۸۹") // "صد پنجاه و شش هزار هفتصد هشتاد و نه"
digit.DigitToWord("-10")     // "منفی ده"

digit.AddCommas(14555478854)          // "14,555,478,854"
n, err := digit.RemoveCommas("4,555") // 4555, nil

nationalid

import "github.com/amiranmanesh/go-persian-tools/nationalid"

nationalid.Validate("0067749828") // true
nationalid.Validate("0684159415") // false

place := nationalid.GetPlaceByIranNationalId("0499370899")
fmt.Println(place.City, place.Province) // شهرری تهران

phonenumbers

import "github.com/amiranmanesh/go-persian-tools/phonenumbers"

phonenumbers.IsPhoneValid("09122221811") // true

details, err := phonenumbers.GetPhoneDetails("09123456789")
if err == nil {
    fmt.Println(details.GetOperator())     // MCI
    fmt.Println(details.GetProvinceList()) // [...]
}

// Normalize the prefix (e.g. to +98)
phonenumbers.PhoneNumberNormalizer("09122221811", "+98") // "+989122221811", nil

A runnable end-to-end demo lives in examples/:

go run ./examples

Development

make test    # run tests
make race    # tests with the race detector
make cover   # tests + coverage profile
make lint    # golangci-lint (https://golangci-lint.run)
make example # run the example program

Contributing

Contributions are welcome — see CONTRIBUTING.md. Please keep gofmt, go vet and the tests green, and add tests for new behavior.

License

Released under the MIT License.

Documentation

Overview

Package persiantools is an anthology of tools for working with Persian (Iranian) data in Go.

It is organized as a set of focused sub-packages:

• bank validate card numbers, resolve banks, and check Sheba (IBAN) codes
• bill parse and validate Iranian utility bills
• digit format numbers and convert digits to Persian words
• nationalid validate national numbers (code-e Melli) and resolve place
• phonenumbers validate and inspect Iranian mobile numbers

Import only the sub-packages you need, for example:

import "github.com/amiranmanesh/go-persian-tools/nationalid"