{"id":13413938,"url":"https://github.com/bojanz/address","last_synced_at":"2026-01-10T23:08:26.646Z","repository":{"id":49339840,"uuid":"302122539","full_name":"bojanz/address","owner":"bojanz","description":"Address handling for Go.","archived":false,"fork":false,"pushed_at":"2024-11-03T11:34:08.000Z","size":123,"stargazers_count":77,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-08T15:36:29.334Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/bojanz/address","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/bojanz.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}},"created_at":"2020-10-07T18:15:27.000Z","updated_at":"2025-02-26T03:48:51.000Z","dependencies_parsed_at":"2023-02-16T01:30:34.717Z","dependency_job_id":"b8bced62-2ea5-41e1-8901-70bbc91e2740","html_url":"https://github.com/bojanz/address","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanz%2Faddress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanz%2Faddress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanz%2Faddress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bojanz%2Faddress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bojanz","download_url":"https://codeload.github.com/bojanz/address/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243642008,"owners_count":20323949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-07-30T20:01:53.177Z","updated_at":"2025-03-14T20:30:48.316Z","avatar_url":"https://github.com/bojanz.png","language":"Go","readme":"# address [![Build](https://github.com/bojanz/address/actions/workflows/build.yml/badge.svg)](https://github.com/bojanz/address/actions/workflows/build.yml) [![Coverage Status](https://coveralls.io/repos/github/bojanz/address/badge.svg?branch=master)](https://coveralls.io/github/bojanz/address?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/bojanz/address)](https://goreportcard.com/report/github.com/bojanz/address) [![PkgGoDev](https://pkg.go.dev/badge/github.com/bojanz/address)](https://pkg.go.dev/github.com/bojanz/address)\n\nHandles address representation, validation and formatting.\n\nInspired by Google's [libaddressinput](https://github.com/google/libaddressinput).\n\nBackstory: https://bojanz.github.io/address-handling-go/\n\n## Features\n\n1. Address struct.\n2. Address formats for ~200 countries.\n3. Regions for ~50 countries, with local names where relevant (e.g: Okinawa / 沖縄県).\n4. Country list, powered by CLDR v46.\n5. HTML formatter.\n6. HTTP handler for serving address formats and regions as JSON: only ~14kb gzipped!\n\n## Address struct\n\nRepresents an address as commonly handled by web applications and APIs.\n\n```go\ntype Address struct {\n\tLine1 string\n\tLine2 string\n\tLine3 string\n\t// Sublocality is the neighborhood/suburb/district.\n\tSublocality string\n\t// Locality is the city/village/post town.\n\tLocality string\n\t// Region is the state/province/prefecture.\n\t// An ISO code is used when available.\n\tRegion string\n\t// PostalCode is the postal/zip/pin code.\n\tPostalCode string\n\t// CountryCode is the two-letter code as defined by CLDR.\n\tCountryCode string\n}\n```\n\nRecipient fields such as FirstName/LastName are not included since they are usually\npresent on the parent (Contact/Customer/User) struct. This allows the package\nto avoid being opinionated about name handling.\n\nThere are three line fields, matching the HTML5 autocomplete spec and many shipping APIs.\nThis leaves enough space for specifying an organization and department, house or hotel\nname, and other similar \"care of\" use cases. When mapping to an API that only has two address lines,\nLine3 can be appended to Line2, separated by a comma.\n\n## Address formats\n\nThe following information [is available](https://github.com/bojanz/address/blob/master/formats.go#L6):\n\n- Which fields are used, and in which order.\n- Which fields are required.\n- Labels for the sublocality, locality, region and postal code fields.\n- Regular expression pattern for validating postal codes.\n- Regions and how to display them in an address.\n\nCertain countries (e.g. China, Japan, Russia, Ukraine) have region names defined in both Latin and local scripts. The script is selected based on locale. For example, the \"ru\" locale will use Russian regions in Cyrilic, while \"ru-Latn\" and other locales will use the Latin version.\n\n[Helpers](https://github.com/bojanz/address/blob/master/address.go#L61) are provided for validating required fields, regions, postal codes.\n\nFormat data was generated from Google's [Address Data](https://chromium-i18n.appspot.com/ssl-address) but isn't\nautomatically regenerated, to allow the community to submit their own corrections directly to the package.\n\n## Countries\n\nThe country list is auto-generated from CLDR. \nUpdating to the latest CLDR release is always one `go generate` away.\n\nMost software uses the CLDR country list instead of the ISO one because the CLDR country names match their colloquial usage more closely (e.g. \"Russia\" instead of \"Russian Federation\"). \n\nTo reduce the size of the included data, this package only includes country names in English.\nTranslated country names can be fetched on the frontend via [Intl.DisplayNames](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DisplayNames). Alternatively, one can plug in [x/text/language/display](https://pkg.go.dev/golang.org/x/text/language/display) by setting a custom CountryMapper on the formatter.\n\n## Formatter\n\nDisplays an address as HTML, using the country's address format.\n\nThe wrapper element (\"p\") and class (\"address\") can be configured.\nThe country name can be omitted, for the use case where all addresses belong to the same country. \n\n```go\naddr := address.Address{\n    Line1:       \"1098 Alta Ave\",\n    Locality:    \"Mountain View\",\n    Region:      \"CA\",\n    PostalCode:  \"94043\",\n    CountryCode: \"US\",\n}\nlocale := address.NewLocale(\"en\")\nformatter := address.NewFormatter(locale)\noutput := formatter.Format(addr)\n// Output:\n// \u003cp class=\"address\" translate=\"no\"\u003e\n// \u003cspan class=\"line1\"\u003e1098 Alta Ave\u003c/span\u003e\u003cbr\u003e\n// \u003cspan class=\"locality\"\u003eMountain View\u003c/span\u003e, \u003cspan class=\"region\"\u003eCA\u003c/span\u003e \u003cspan class=\"postal-code\"\u003e94043\u003c/span\u003e\u003cbr\u003e\n// \u003cspan class=\"country\" data-value=\"US\"\u003eUnited States\u003c/span\u003e\n// \u003c/p\u003e\n\naddr = address.Address{\n    Line1:       \"幸福中路\",\n    Sublocality: \"新城区\",\n    Locality:    \"西安市\",\n    Region:      \"SN\",\n    PostalCode:  \"710043\",\n    CountryCode: \"CN\",\n}\nlocale := address.NewLocale(\"zh\")\nformatter := address.NewFormatter(locale)\nformatter.NoCountry = true\nformatter.WrapperElement = \"div\"\nformatter.WrapperClass = \"postal-address\"\noutput := formatter.Format(addr)\n// Output:\n// \u003cdiv class=\"postal-address\" translate=\"no\"\u003e\n// \u003cspan class=\"postal-code\"\u003e710043\u003c/span\u003e\u003cbr\u003e\n// \u003cspan class=\"region\"\u003e陕西省\u003c/span\u003e\u003cspan class=\"locality\"\u003e西安市\u003c/span\u003e\u003cspan class=\"sublocality\"\u003e新城区\u003c/span\u003e\u003cbr\u003e\n// \u003cspan class=\"line1\"\u003e幸福中路\u003c/span\u003e\n// \u003c/div\u003e\n```\n","funding_links":[],"categories":["开源类库","Text Processing","Bot Building","文本处理","Relational Databases","Template Engines","Natural Language Processing"],"sub_categories":["未归类","Formatters","格式器","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbojanz%2Faddress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbojanz%2Faddress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbojanz%2Faddress/lists"}