{"id":13581254,"url":"https://github.com/grokify/gophonenumbers","last_synced_at":"2026-04-19T16:03:00.033Z","repository":{"id":37930345,"uuid":"119566319","full_name":"grokify/gophonenumbers","owner":"grokify","description":"API Client and CLI app for numverify.com to verify phone number and list countries.","archived":false,"fork":false,"pushed_at":"2026-04-06T05:12:03.000Z","size":398,"stargazers_count":10,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T07:38:45.222Z","etag":null,"topics":["cli","cli-command","cli-utility","go","go-cli","go-client"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grokify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-01-30T16:56:48.000Z","updated_at":"2026-04-06T05:09:37.000Z","dependencies_parsed_at":"2024-05-06T15:13:39.102Z","dependency_job_id":"2832091a-9983-4bda-af47-717eb5697ef9","html_url":"https://github.com/grokify/gophonenumbers","commit_stats":{"total_commits":207,"total_committers":2,"mean_commits":103.5,"dds":0.3285024154589372,"last_synced_commit":"43c6cdb47eff62f14f1e199911fc527840a6b1b3"},"previous_names":["grokify/numverify","grokify/go-numverify","grokify/go-phonenumber"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/grokify/gophonenumbers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grokify%2Fgophonenumbers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grokify%2Fgophonenumbers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grokify%2Fgophonenumbers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grokify%2Fgophonenumbers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grokify","download_url":"https://codeload.github.com/grokify/gophonenumbers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grokify%2Fgophonenumbers/sbom","scorecard":{"id":446125,"data":{"date":"2025-08-11","repo":{"name":"github.com/grokify/gophonenumbers","commit":"066be83d86d99a1f35cca1312a9e80a4ba17333b"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.1,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/9 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/lint.yaml:1","Warn: no topLevel permission defined: .github/workflows/test.yaml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/lint.yaml:11: update your workflow using https://app.stepsecurity.io/secureworkflow/grokify/gophonenumbers/lint.yaml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/lint.yaml:13: update your workflow using https://app.stepsecurity.io/secureworkflow/grokify/gophonenumbers/lint.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yaml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/grokify/gophonenumbers/test.yaml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/test.yaml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/grokify/gophonenumbers/test.yaml/master?enable=pin","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 21 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":6,"reason":"4 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2025-3487 / GHSA-hcg3-q754-cr77","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw","Warn: Project is vulnerable to: GO-2025-3488 / GHSA-6v2p-p543-phr9"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T06:46:10.520Z","repository_id":37930345,"created_at":"2025-08-19T06:46:10.520Z","updated_at":"2025-08-19T06:46:10.520Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32012787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-command","cli-utility","go","go-cli","go-client"],"created_at":"2024-08-01T15:01:59.667Z","updated_at":"2026-04-19T16:03:00.027Z","avatar_url":"https://github.com/grokify.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# GoPhoneNumbers\n\n[![Go CI][go-ci-svg]][go-ci-url]\n[![Go Lint][go-lint-svg]][go-lint-url]\n[![Go SAST][go-sast-svg]][go-sast-url]\n[![Go Report Card][goreport-svg]][goreport-url]\n[![Docs][docs-godoc-svg]][docs-godoc-url]\n[![Visualization][viz-svg]][viz-url]\n[![License][license-svg]][license-url]\n\n [go-ci-svg]: https://github.com/grokify/gophonenumbers/actions/workflows/go-ci.yaml/badge.svg?branch=main\n [go-ci-url]: https://github.com/grokify/gophonenumbers/actions/workflows/go-ci.yaml\n [go-lint-svg]: https://github.com/grokify/gophonenumbers/actions/workflows/go-lint.yaml/badge.svg?branch=main\n [go-lint-url]: https://github.com/grokify/gophonenumbers/actions/workflows/go-lint.yaml\n [go-sast-svg]: https://github.com/grokify/gophonenumbers/actions/workflows/go-sast-codeql.yaml/badge.svg?branch=main\n [go-sast-url]: https://github.com/grokify/gophonenumbers/actions/workflows/go-sast-codeql.yaml\n [goreport-svg]: https://goreportcard.com/badge/github.com/grokify/gophonenumbers\n [goreport-url]: https://goreportcard.com/report/github.com/grokify/gophonenumbers\n [docs-godoc-svg]: https://pkg.go.dev/badge/github.com/grokify/gophonenumbers\n [docs-godoc-url]: https://pkg.go.dev/github.com/grokify/gophonenumbers\n [viz-svg]: https://img.shields.io/badge/visualizaton-Go-blue.svg\n [viz-url]: https://mango-dune-07a8b7110.1.azurestaticapps.net/?repo=grokify%2Fgophonenumbers\n [license-svg]: https://img.shields.io/badge/license-MIT-blue.svg\n [license-url]: https://github.com/grokify/gophonenumbers/blob/master/LICENSE\n\nA Go library for phone number parsing, formatting, validation, and geolocation. Includes clients for Numverify and Twilio Lookup APIs.\n\n## Features\n\n- **Phone Number Parsing**: Parse E.164, national, and international formats\n- **NANP Components**: Extract area code, exchange code, and line number from North American numbers\n- **Multiple Formats**: Get E.164, national, international, and RFC3966 formats\n- **Geolocation**: US area code to geographic coordinates mapping (embedded data, no external files)\n- **Distance Calculation**: Great circle distance between area codes\n- **Fictitious Numbers**: Generate valid US fictitious phone numbers (555-01XX range)\n- **API Clients**: Numverify and Twilio Lookup API integrations\n- **CLI Tools**: Command-line apps for number validation and lookup\n\n## Installation\n\n```bash\ngo get github.com/grokify/gophonenumbers\n```\n\n## Quick Start\n\n### Parse and Format Phone Numbers\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/grokify/gophonenumbers\"\n)\n\nfunc main() {\n    // Parse an E.164 number into multiple formats\n    formats, err := gophonenumbers.FormatsParse(\"+16505551234\", \"US\")\n    if err != nil {\n        panic(err)\n    }\n\n    fmt.Println(\"E.164:\", formats.E164)           // +16505551234\n    fmt.Println(\"National:\", formats.National)    // (650) 555-1234\n    fmt.Println(\"International:\", formats.International) // +1 650-555-1234\n    fmt.Println(\"RFC3966:\", formats.RFC3966)      // tel:+1-650-555-1234\n}\n```\n\n### Extract NANP Components\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/grokify/gophonenumbers\"\n)\n\nfunc main() {\n    num := gophonenumbers.Number{E164Number: \"+16505551234\"}\n    comp, err := num.NANPComponents()\n    if err != nil {\n        panic(err)\n    }\n\n    fmt.Println(\"Country Code:\", comp.CountryCode)     // 1\n    fmt.Println(\"Area Code:\", comp.NANPAreaCode)       // 650\n    fmt.Println(\"Exchange Code:\", comp.NANPExchangeCode) // 555\n    fmt.Println(\"Line Number:\", comp.NANPLineNumber)   // 1234\n}\n```\n\n### US Area Code Geolocation\n\nThe library includes embedded US area code geolocation data - no external files required.\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/grokify/gophonenumbers\"\n)\n\nfunc main() {\n    // Load embedded area code data\n    a2g := gophonenumbers.NewAreaCodeToGeo()\n    if err := a2g.ReadData(); err != nil {\n        panic(err)\n    }\n\n    // Get area code info\n    aci := a2g.AreaCodeInfos[650] // San Francisco Bay Area\n    fmt.Printf(\"Area Code 650: Lat %.4f, Lon %.4f\\n\",\n        aci.Point.Lat(), aci.Point.Lng())\n\n    // Calculate distance between area codes\n    dist, _ := a2g.GcdAreaCodes(650, 212) // SF to NYC\n    fmt.Printf(\"Distance 650 to 212: %.0f km\\n\", dist)\n}\n```\n\n### Generate Fictitious Phone Numbers\n\nGenerate valid US fictitious numbers in the 555-01XX range for testing:\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/grokify/gophonenumbers\"\n)\n\nfunc main() {\n    a2g := gophonenumbers.NewAreaCodeToGeo()\n    if err := a2g.ReadData(); err != nil {\n        panic(err)\n    }\n\n    fng := gophonenumbers.NewFakeNumberGenerator(a2g.AreaCodes())\n\n    // Generate a random fictitious number\n    num, _ := fng.RandomLocalNumberUS()\n    fmt.Printf(\"Fictitious number: +%d\\n\", num)\n\n    // Generate unique numbers\n    set := map[uint64]int8{}\n    for i := 0; i \u003c 5; i++ {\n        num, set, _ = fng.RandomLocalNumberUSUnique(set)\n        fmt.Printf(\"Unique number %d: +%d\\n\", i+1, num)\n    }\n}\n```\n\n## API Clients\n\n### Numverify\n\nValidate phone numbers using the [Numverify API](https://numverify.com/documentation):\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    nv \"github.com/grokify/gophonenumbers/numverify\"\n)\n\nfunc main() {\n    client := nv.Client{AccessKey: \"your-access-key\"}\n\n    resp, _, _, err := client.Validate(nv.Params{Number: \"+16505551234\"})\n    if err != nil {\n        panic(err)\n    }\n\n    if resp.Success != nil {\n        fmt.Println(\"Valid:\", resp.Success.Valid)\n        fmt.Println(\"Carrier:\", resp.Success.Carrier)\n        fmt.Println(\"Line Type:\", resp.Success.LineType)\n    }\n}\n```\n\n### Twilio Lookup\n\nLook up phone numbers using the [Twilio Lookup API](https://www.twilio.com/docs/lookup/api):\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/grokify/gophonenumbers/twilio\"\n)\n\nfunc main() {\n    client := twilio.NewClient(\"account-sid\", \"auth-token\")\n\n    info, err := client.Validate(\"+16505551234\", \u0026twilio.Params{Type: \"carrier\"})\n    if err != nil {\n        panic(err)\n    }\n\n    fmt.Println(\"Phone Number:\", info.PhoneNumber)\n    fmt.Println(\"Carrier:\", info.Carrier.Name)\n}\n```\n\n## CLI Tools\n\n### Numverify CLI\n\n```bash\n# Install\ngo install github.com/grokify/gophonenumbers/cmd/numverify@latest\n\n# Validate a number\nnumverify -t=\u003caccess-key\u003e -n=+16505551234\n\n# Using .env file\nnumverify -e=/path/to/.env -n=+16505551234\n\n# List supported countries\nnumverify -t=\u003caccess-key\u003e -c\n```\n\n### Area Code Distance\n\n```bash\n# Install\ngo install github.com/grokify/gophonenumbers/cmd/areacode_distance@latest\n\n# Calculate distance between area codes\nareacode_distance 650 212\n```\n\n## Data Reference\n\n### Embedded Data\n\nThe library embeds US area code geolocation data from the [Area Code Geolocation Database](https://github.com/ravisorg/Area-Code-Geolocation-Database). No external files or GOPATH configuration required.\n\n### Number Components\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| Country Code | ITU-T E.164 country code | 1 (US/Canada) |\n| Area Code (NPA) | Numbering Plan Area code | 650 |\n| Exchange Code (NXX) | Central office code | 555 |\n| Line Number | Subscriber number | 1234 |\n\n### Fictitious Numbers\n\nThe library generates numbers in the reserved 555-01XX range per [NANPA guidelines](https://www.nanpa.com/number_resource_info/555_service_numbers.html). These numbers are safe for testing and will never conflict with real numbers.\n\n## Contributing\n\nContributions are welcome. Please open an issue or submit a pull request.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrokify%2Fgophonenumbers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrokify%2Fgophonenumbers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrokify%2Fgophonenumbers/lists"}