{"id":19777471,"url":"https://github.com/ilib-js/ilib-address","last_synced_at":"2025-04-30T19:32:38.525Z","repository":{"id":61899256,"uuid":"556148983","full_name":"iLib-js/ilib-address","owner":"iLib-js","description":"Library to parse and format mailing addresses","archived":false,"fork":false,"pushed_at":"2024-10-29T20:07:52.000Z","size":4236,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T22:41:39.729Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iLib-js.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":"2022-10-23T06:54:04.000Z","updated_at":"2022-11-08T20:17:14.000Z","dependencies_parsed_at":"2023-11-26T19:52:31.166Z","dependency_job_id":null,"html_url":"https://github.com/iLib-js/ilib-address","commit_stats":{"total_commits":22,"total_committers":2,"mean_commits":11.0,"dds":"0.045454545454545414","last_synced_commit":"a33d12d2bce9bfcf8487c8f65e8c780c980e870a"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-address/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224222245,"owners_count":17275981,"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-11-12T05:25:09.319Z","updated_at":"2024-11-12T05:25:09.787Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ilib-address\n\nLibrary to parse and format mailing addresses.\n\nAddress Parsing and Formatting in iLib\n===================================\n\nThis tutorial shows you how you can parse mailing addresses in various locales, and format them again easily.\n\nMotivation\n----------\n\nWhy would you want to parse and format addresses?\n\nLet's say you have a part of your web site that allows your users to enter some contacts. You may have a name field, some phone number fields, an address field and an email field. The address field is a single field where they can type the whole address of their contact. Now, you would probably also have a page that lists the contacts in alphabetical order, and the user may be able to click on address column to sort by that field. What if they wanted to sort based on country/region, or on the city?\n\nThe problem is... what is the country, or zip or city for each address? It turns out that the postal authority in each country can define the standard order for the parts of an address, and that each country is different, even when they speak the same language.\n\nNow things get even more complicated when you have to support multiple languages or scripts. Some places typically reverse the order of the address parts. For example, in Chinese, you would typically write the parts in order from largest (country \"China\") to medium (city \"Beijing\") to smallest (building number or street address). It gets even more complicated in places with complicated histories, such as Hong Kong, where you would write the exact same address in Chinese order when you are writing with Chinese characters, and in British order when writing in Latin characters.\n\nThere is even more fun to be had if you try to parse names in other countries where that other country uses a different script or order. For example, you may have a US contact list with a Chinese address for one of your contacts. In that case, the address would probably have have something like \"China\" or \"PRC\" at the end of it in Latin characters so that the US post office knows to send the letter to China. But, the rest of the address is written in Chinese with Chinese order. This is a sort of hybrid address.\n\nGiven all the above, the humble Javascript programmer needs a little help to parse and format addresses so they don't have to be an expert in the address formats for a large number of countries. Enter iLib.\n\nParsing Addresses with iLib-address\n---------------------------\n\nParsing addresses is a simple matter of creating an instance of the Address class. Here is an example:\n\n~~~~~~\nimport { Address } from \"ilib-address\";\n\nconst address = new Address(\"LG Silicon Valley Lab\\n5150 Great America Pkwy\\nSanta Clara, CA 95054\\nUSA\");\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\n\nvar address = new Address(\"LG Silicon Valley Lab\\n5150 Great America Pkwy\\nSanta Clara, CA 95054\\nUSA\");\n~~~~~~\n\nNow, assuming your current locale is en-US, the \"address\" variable should contain the following properties:\n\n~~~~~~\n{\n    country: \"USA\",\n    countryCode: \"US\",\n    postalCode: \"95054\",\n    region: \"CA\",\n    locality: \"Santa Clara\",\n    streetAddress: \"LG Silicon Valley Lab, 5150 Great America Pkwy\"\n}\n~~~~~~\n\nParsing in Other Countries\n--------------------------\n\nJust like other iLib classes, you can pass in options to the constructor to control how the parsing proceeds. For example, let's say you want to parse the address in Korea instead, even though your current locale is en-US:\n\n~~~~~~\nimport { Address } from \"ilib-address\";\n\nconst address = new Address(\"한국 서울시 영등포구 여의대로 128 LG트윈타워\", {\n    locale: \"ko-KR\"\n});\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\n\nvar address = new Address(\"한국 서울시 영등포구 여의대로 128 LG트윈타워\", {\n    locale: \"ko-KR\"\n});\n~~~~~~\n\nNow the properties are:\n\n~~~~~~\n{\n    country: \"한국\",\n    countryCode: \"KR\",\n    locality: \"서울시\",\n    streetAddress: \"영등포구 여의대로 128 LG트윈타워\"\n}\n~~~~~~\n\nWithout the explicit locale option, the parser will use the current locale to parse the string.\n\nParsing Addresses with Latin Script\n-----------------------------------\n\nLet's say your US contact list contains an address outside of the US. Parsing would be a little more difficult if the foreign address is in a different script than the US (ie. non-Latin characters).\n\nFortunately, the Address parser can recognize the foreign country, and can automatically use the rules of that country to parse the rest of the address. Note that for many countries, you can write addresses in Latin or the native script, and Address will use the correct set of rules to parse each of them, depending on what characters it finds in the string. Here is an example:\n\n~~~~~~\nimport { Address } from \"ilib-address\";\n\n// note: no locale is specified here!\nconst address = new Address(\"LG Electronics, Gasan-dong, Geumcheon-gu, Seoul, South Korea\");\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\n\n// note: no locale is specified here!\nvar address = new Address(\"LG Electronics, Gasan-dong, Geumcheon-gu, Seoul, South Korea\");\n~~~~~~\n\nNow the properties are the same as when the locale was specified explicitly:\n\n~~~~~~\n{\n    country: \"South Korea\",\n    countryCode: \"KR\",\n    locality: \"Seoul\",\n    streetAddress: \"LG Electronics, Gasan-dong, Geumcheon-gu\"\n}\n~~~~~~\n\n\nIt Doesn't Work All the Time\n----------------------------\n\nThere are many types of addresses and strings where the parser's heuristics do not work properly. Don't expect that it should work in 100% of the cases!\n\nIf needed, the parser can be upgraded in the future to support more things and special cases. Please let us know if you have a very common case that is not supported. (email to \"marketing@translationcircle.com\")\n\nFormatting Addresses\n----------------\n\nIn some contacts services, such as Google Contacts, addresses are given as whole addresses in a single string, and you need the parser documented in the previous section to decipher the parts.\n\nBut what if you have the address fields already separated? How would you format them together in the right order?\n\nThere is where you would use the class AddressFmt to reassemble the parts into a single string. Here is an example:\n\n~~~~~~\nimport { Address, AddressFmt } from \"ilib-address\";\n\n// presumably, these parts came from your database or contacts list\nconst address = new Address({\n    country: \"USA\",\n    countryCode: \"US\",\n    postalCode: \"95054\",\n    region: \"CA\",\n    locality: \"Santa Clara\",\n    streetAddress: \"LG Silicon Valley Lab, 5150 Great America Pkwy\"\n});\nconst af = new AddressFmt();\nconst formatted = af.format(address);\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\nvar AddressFmt = ilibAddres.AddressFmt;\n\n// presumably, these parts came from your database or contacts list\nvar address = new Address({\n    country: \"USA\",\n    countryCode: \"US\",\n    postalCode: \"95054\",\n    region: \"CA\",\n    locality: \"Santa Clara\",\n    streetAddress: \"LG Silicon Valley Lab, 5150 Great America Pkwy\"\n});\nvar af = new AddressFmt();\nvar formatted = af.format(address);\n~~~~~~\n\nNow the name in the \"formatted\" variable will appear as the string:\n\n\u003e LG Silicon Valley Lab\n\u003e 5150 Great America Parkway\n\u003e Santa Clara, CA 95054\n\u003e USA\n\nFormatting Addresses in Foreign Countries\n----------------------\n\nLet's say your contact list contains an address outside of your current locale. In this case, iLib will use the format data for the current locale to format the country, and load the format data for that foreign country and use those to format the parts of address inside that foreign country.\n\nFor example, let's say the current iLib locale is \"en-US\", and the user has a contact in Germany. Here is how the code would look:\n\n~~~~~~\nimport { Address, AddressFmt } from \"ilib-address\";\n\nconst address = new Address({\n    country: \"Germany\",\n    countryCode: \"DE\",\n    postalCode: \"40880\",\n    locality: \"Ratingen\",\n    streetAddress: \"LG Electronics Deutschland GmbH, Berliner Str 93\"\n});\nconst af = new AddressFmt();\nconst formatted = af.format(address);\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\nvar AddressFmt = ilibAddressFmt.AddressFmt;\n\nvar address = new Address({\n    country: \"Germany\",\n    countryCode: \"DE\",\n    postalCode: \"40880\",\n    locality: \"Ratingen\",\n    streetAddress: \"LG Electronics Deutschland GmbH, Berliner Str 93\"\n});\nvar af = new AddressFmt();\nvar formatted = af.format(address);\n~~~~~~\n\nNote that you should preserve the countryCode field in the database that the parser gave you, so that you can pass it back to the formatter again as above.\n\nHere is what the value of the \"formatted\" variable will end up being:\n\n\u003e LG Electronics Deutschland GmbH\n\u003e Berliner Str 93\n\u003e 40880 Ratingen\n\u003e Germany\n\nNote that the name of the country is in English still, because when you put an envelope into the mail in the US, the English-speaking US Post employee will be reading the address and looking for the name of the country where the the letter should be sent. The rest of the address above the \"Germany\" line is formatted according to the German conventions.\n\nMixed Asian and Western Addresses\n---------------------------------\n\nThis gets even more tricky when mixing Asian and Western together. Let's say you had an address in Korea in your English/US contact list. In Korean, you would put the name of the country at the top (it goes from biggest to smallest). In the US, you would put the name of the country at the bottom. Since it is being mailed from the US to Korea, you start off with US rules, and then use Korean rules for the rest of the address. Here is how it would look:\n\n~~~~~~\nimport { Address, AddressFmt } from \"ilib-address\";\n\n// presumably, these parts came from your database or contacts list\nconst address = new Address({\n    country: \"Republic of Korea\",\n    countryCode: \"KR\",\n    locality: \"서울시\",\n    streetAddress: \"영등포구 여의대로 128 LG트윈타워\"\n});\nconst af = new AddressFmt();\nconst formatted = af.format(address);\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\nvar AddressFmt = ilibAddress.ilibAddressFmt;\n\n// presumably, these parts came from your database or contacts list\nvar address = new Address({\n    country: \"Republic of Korea\",\n    countryCode: \"KR\",\n    locality: \"서울시\",\n    streetAddress: \"영등포구 여의대로 128 LG트윈타워\"\n});\nvar af = new AddressFmt();\nvar formatted = af.format(address);\n~~~~~~\n\nHere is what the value of the \"formatted\" variable will end up being:\n\n\u003e 서울시 영등포구 여의대로 128 LG트윈타워\n\u003e Republic of Korea\n\nLatin Script in Asian Addresses\n-------------------------------\n\nSome addresses in Asia are written in Latin script for the convenience of the reader. In this case, the locale data for many of the Asian locales has two sets of rules: one for Asian addresses that are written in Asian scripts, and another for those that are written in Latin script.\n\nHere is an example in Hong Kong, where because of its unique history, it is very common to find both Chinese character and Latin character addresses.\n\n~~~~~~\nimport { Address, AddressFmt } from \"ilib-address\";\n\n// presumably, these parts came from your database or contacts list\nconst address = new Address({\n    country: \"Hong Kong\",\n    countryCode: \"HK\",\n    locality: \"North Point\",\n    streetAddress: \"5F, 633 King's Road\"\n});\nconst af = new AddressFmt();\nconst formatted = af.format(address);\n~~~~~~\n\nor in older Javascript:\n\n~~~~~~\nvar ilibAddress = require(\"ilib-address\");\nvar Address = ilibAddress.Address;\nvar AddressFmt = ilibAddress.AddressFmt;\n\n// presumably, these parts came from your database or contacts list\nvar address = new Address({\n    country: \"Hong Kong\",\n    countryCode: \"HK\",\n    locality: \"North Point\",\n    streetAddress: \"5F, 633 King's Road\"\n});\nvar af = new AddressFmt();\nvar formatted = af.format(address);\n~~~~~~\n\nThe formatter does the right thing here for the script. Here is what the value of the \"formatted\" variable will end up being:\n\n\u003e 5F, 633 King's Road\n\u003e North Point\n\u003e Hong Kong\n\n## License\n\nCopyright © 2022-2023, JEDLSoft\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n## Release Notes\n\n### v1.0.1\n\n- Updated dependencies\n- published the locale data in the npm package that was missing in the\n  initial release. (whoops!)\n\n### v1.0.0\n\n- Initial version copied from ilib 14.15.2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-address/lists"}