International Address Parser documentation

	//Instanciate parser and standardizer, only once
		AddressParser addressParser = AddressParser.getInstance();

		String rawAddress = "650 Castro Street Mountain View, CA, 94041-2021 USA";
				
		boolean standardizeAfterParsing = false;
		Address address = addressParser.parse(rawAddress,"..",standardizeAfterParsing);


		System.out.println("housenumber : "+address.getHouseNumber());
		System.out.println("streetType : "+address.getStreetType());
		System.out.println("streetname : "+address.getStreetName());
		System.out.println("PObox : "+address.getPOBox());
		System.out.println("city : "+address.getCity());
		System.out.println("district : "+address.getDistrict());
		System.out.println("state : "+address.getState());
		//see all fields description above...

		// do what ever you want with the result, (e.g : print the result on the console) 
		System.out.println(address);

if you use HTTP connector, You can also call an URL like this :

http://HOST:PORT/local-address-parser/addressparser?address=650%20Castro%20Street%20Suite%20300%20Mountain%20View,%20CA,%2094041-2021%20USA&country=..

How to buy

If you are interested in address parsing and standardization (offline or online), you can aquire a license : contact us to get further informations.

The parser and standardizer are not open source, you buy a compiled versions that is royalty free. You can test the relevance by using the online version. If you're satisfied, we can go further, and we send you a pack with the jar OR the DLL, with some code samples.

we can send you the license, if you need it.

Javadoc

The javadoc is available at https://www.address-parser.net/documentation/javadoc/

Sample code

Don't put an address with an adressee, it is not supported

In Java

There is two ways to access the parser in Java :

• The offline way, when you have bought the Jar and you want to access the parser / standardizer directly. You need Java at least java 1.5, but get greater performance with 1.6 and above. We strongly recomand sun/oracle JRE (avoid openJdk, and others). No external dependencies are needed.

  	//Instanciate parser and standardizer, only once
  		AddressParser addressParser = AddressParser.getInstance();
  		AddressStandardizer standardizer = AddressStandardizer.getInstance();//if enabled
  		AddressFormater formater = AddressFormater.getInstance();
  
  		String rawAddress = "101 Avenue des Champs-Elysées 75008 Paris";
  
  		//you can try to detect the country
  		CountryDetector detector = CountryDetector.getInstance();
  		String countryCode = detector.getCountryCode("7580 Commerce Center Dr ALABAMA");
  		System.out.println("detected country=" + countryCode);
  		
  		//you can parse AND standardize in on method call
  		boolean standardizeAfterParsing = false;
  		Address address = addressParser.parse(rawAddress,"FR",standardizeAfterParsing);
  		//note that the country code can be omited. This way, country will be autodetected.
  	        //if country can not be detected, the parsing will fail.
  
  
  		System.out.println("housenumber : "+address.getHouseNumber());
  		System.out.println("streetType : "+address.getStreetType());
  		System.out.println("streetname : "+address.getStreetName());
  		System.out.println("PObox : "+address.getPOBox());
  		System.out.println("city : "+address.getCity());
  		System.out.println("district : "+address.getDistrict());
  		System.out.println("state : "+address.getState());
  		//see all fields description above...
  
  		//You can use the standardizer separately
  		address = standardizer.standardize(address);
  		formater.getEnvelopeAddress(address, DisplayMode.HTML);
  		
  		
  
  		// do what ever you want with the result, (e.g : print the result on the console) 
  		System.out.println(address);
  

  
  
  The java packaging can be run on every OS that support Java (mac, windows, linux, solaris, Sun,...). If an OS support Java AND .NET (e.g : linux with Mono develop), The Java packaging should always be prefered to the .NET one.
• The onLine way, when you want to use the webservice. In this case, you use the addressparser client library (provided when you have subscribed to the webservice, or use the free access), you can also use a code of your own.

  	
  		String URL = AddressParserClient.DEFAULT_ADDRESS_PARSER_BASE_URL;
  		//URL = "http://The.URL.given.when.I.have.subscribed/";
  		AddressParserClient addressParser = new AddressParserClient(URL);
  		String rawAddress = "101 Avenue des Champs-Elysées 75008 Paris";
  		AddressQuery query =new AddressQuery(rawAddress, "FR");
  		boolean standardizeAfterParsing = false;
  		query.setStandardize(standardizeAfterParsing);
  		
  	        //When using the Premium access,you need to sepcify an apiKey (not required when using the free access).
  		query.setApikey("KEY_PROVIDED_WHEN_I_HAVE_SUBSCRIBED_TO_PREMIUM");
  		
  		
  		AddressResultsDto results = addressParser.execute(query);
  		System.out.println("Query tooks "+results.getQTime()+" ms and"+
  			" return "+results.getNumFound()+" result(s)");
  		for (Address address : results.getResult()){
  			System.out.println("housenumber : "+address.getHouseNumber());
  			System.out.println("streetType : "+address.getStreetType());
  			System.out.println("streetname : "+address.getStreetName());
  			System.out.println("PObox : "+address.getPOBox());
  			System.out.println("city : "+address.getCity());
  			System.out.println("district : "+address.getDistrict());
  			System.out.println("state : "+address.getState());
  			//see all fields description above...
  		}
  

In C# .NET API

Here is a sample code in C#, that show how to use the parser/standardizer. An external library is required and provided in the packaging. The .NET packaging is supported by Windows (of course) and Linux with Mono develop. If you plan to use address parser/standardizer on Linux/Unix, it is strongly recomanded to use the java packaging. If you interested in .NET packaging, you should tell us what is the the .NET framework you will use, We will give you an optimized version.

	     using System;

	     using com.gisgraphy.addressparser;
	     using com.gisgraphy.addressparser.format;
	     using com.gisgraphy.addressparser.standardization;

       	     //instanciate parser and standardizer, only once
             AddressParser ap = AddressParser.getInstance();
             AddressStandardizer standardizer = AddressStandardizer.getInstance();//if enabled
             CountryDetector detector = CountryDetector.getInstance();

	     //detect country if needed
             Console.WriteLine("starting country detection...");
             String countrycode = detector.getCountryCode("333 North Bedford Rd2");
	
	     //parse
             Boolean standardizeAfterParsing = false;
             Address address= ap.parse("123 main street northwest,apartment 22", "US",standardizeAfterParsing);
             Console.WriteLine("parsed address : " +address);
             Console.WriteLine("standardized address : "+standardizer.standardize(address));

	     //other example but without countrycode provided. This way, country will be autodetected.
             //if country can not be detected, the parsing will fail
             address = ap.parse("265 Boulevard Hymus #1900", null);
             Console.WriteLine("parsed address : " +address);
             Console.WriteLine("standardized address : " + standardizer.standardize(address));

Note that actually, There is no client library in C# to access the webservice.

Webservice

Webservice is, for people that always want the latest version, or want to use the parser or the standardizer in other languages than java or c#. The webservice is load balanced and can accept as many request as needed.
Here is a summary of the Web parameters that address parser accepts :

Parameter name	required	Default value	description
address	yes	none	The address to parse
country	yes	none	The ISO 3166 country code of the country of the address
standardize	no	false	Whether the address should be standardize after been parsed
format	no	XML	Output format of the response : XML, JSON, PHP, PYTHON, RUBY, PHP
callback	no	none	The callback method name, used to wrap the content into a method name, must be alphanumeric and operate only for script outputformat (json,php,ruby,python)
indent	no	true	Wether the feed should be indented, the value can be 'true','false', or 'on' (this is usefull if you use a checkbox in a form)

Webservice output Formats

The following languages can be outputed by the webservices :

• XML
• Json
• Php
• Ruby
• Python
• YAML

Performance

The parser and standardizer are not a compromise between relevance and performance. A minimum of memory is needed to handle the knowledge database, but the performance depends on the CPU (CPU-bounds). A recent personal computer can parse between 100 and 130 addresses/seconds/thread. On a good core i7 you can parse nearly 1000 adresses/seconds. Note that .net version can have less performances.

Bug report

Relevance and performance are very important for us. We have a lot of unit and integration tests to assure a good quality to the final users.

There is a dedicated page that allows anyone to do bug reporting. Simply fill the web form and it automatically create a unit test that will be added, after verification, to the test suite. This way, the test suite (more than 1200 tests, when this documentation was writen) grows with feedbacks, and avoid regressions when modifications are made.

Output fields

Here are an exhaustive list of all the fields that the address parser can extract

field	description	Examples of value	Examples in address
id	id that identify a feature	123456	N/A
confidence	An indicator that mesure how the parser is confident for the result	MAX,MEDIUM,MIN	Learn More about confidence
name	Name of the place, it is null in case of address but filled if common place. Name is different than recipient name.	Tour eiffel	Tour eiffel Paris
recipientName	Name of the organisation or person at the given address	Jack bauer	Jack Bauer street of philadelphia city, apt 5A, Washington
houseNumber	Official number assigned to an address by the municipality, several languages supported	3;151-125;eight	123 street of philadelphia city, apt 5A, Washington
houseNumberInfo	All informations that give extra informations on the house number	bis, ter, quater,	125 bis rue de la france 75000 Paris
streetName	The official name of the street or the ordinal number	Main, 8TH	100 MAIN ST POB 1022 SEATTLE WA 98104
streetType	The type of the street	street,st,bd,dr,bvd,...	100 MAIN ST POB 1022 SEATTLE WA 98104
city	The city or locality, A small town or village name sometimes included in an address when the Delivery Point is outside the boundary of the main Post Town that serves it.	APPLEFORD	Leda Engineering Ltd APPLEFORD ABINGDON OX14 4PG
dependentLocality	"Sub" city attached to a big city	Dublin	boulevard of liberty Washington
PostTown	a city it is required part of all postal addresses in the United Kingdom	London	49 Featherstone Street LONDON EC1Y 8SY
state	The state or county when applicable (often the 1st administative level), can be fullName or abbreviation	WA	100 MAIN ST POB 1022 SEATTLE WA 98104
prefecture	The 2nd level of China administrative level	Sùzhōu,福州市	10 Don St, Dongcheng, Beijing 北京市朝阳区望京广顺北大街222号星源公寓D座
ward	The adm level of Japan	Chūō-ku, 中央区	Tōkyō-to Chūō-ku
citySubdivision	subdivision of a city or municipality	-	-
district	The district, mainly use for Russia and China (county level)	ALEKSCEVSKTY (r-n)	ul. Lesnaya d. 5 pos. Lesnoe ALEKSCEVSKTY r-n VORONEJSKAYA obl 247112 RUSSIAN FEDERATION. 36 BAOSHAN JIUCUN, BAOSHAN DISTRICT 201900 SHANGHAI
quarter	A section of an urban settlement	DOĞANBEY MAH(turkey),French Quarter	Mebusevleri Mah. Önder Cad. Ankara Ap. 11/8 ALEKSCEVSKTY
zipCode	The zip or post code	98104	100 MAIN ST POB 1022 SEATTLE WA 98104
extraInfo	Informations on floor, unit, and sometimes POBOX,..	floor 6,Hangar of the century	100 MAIN ST POB 1022 SEATTLE WA 98104 100 MAIN ST 3rd floor SEATTLE WA 98104
SuiteType	Informations on the unit, mainly used and filled by standardizer	APT, #	123 Main street northwest , apartment 22 SEATTLE WA 98104
SuiteNumber	Informations on the unit, mainly used and filled by standardizer	22	123 Main street northwest ,apartment 22 SEATTLE WA 98104
POBox	Post office box, Boite postale, Casilla de Correo,..	POB 45, POBOX 52,boite postale 89,Casilla de Correo 17	100 MAIN ST POB 1022 SEATTLE WA 98104 100 MAIN ST 3rd floor SEATTLE WA 98104
POBoxInfo	extra info on Post office box, Boite postale, Casilla de Correo,..	CEDEX 01	5, rue Foobar, 75725 Paris CEDEX 01
POBoxAgency	Agency where the office box, Boite postale, Casilla de Correo is	KHOURIBGA PRINCIPALE	P.O 1737 KHOURIBGA PRINCIPALE 25005 KHOURIBGACEDEX
preDirection	The cardinal direction before the name of the street	N,NE;North	N broadway bd
postDirection	The cardinal direction after the name of the street	N,NE;North	boulevard of liberty north Washington
streetNameIntersection	The official name of the intersection street	Main	N street of philadelhia & W boulevard of liberty Washington
streetTypeIntersection	The type of the intersection street	street,st,bd,dr,bvd,...	N street of philadelhia & W boulevard of liberty Washington
preDirectionIntersection	The cardinal direction before the name of the intersection street	N,NE;North	N street of philadelhia & W boulevard of liberty Washington
postDirectionIntersection	The cardinal direction after the name of the intersection street	N,NE;North	N street of philadelhia & boulevard of liberty SOUTH Washington
civicNumberSuffix	The number that follow the house number (Canada only)	1/2	10-123 1/2 main street NW MONTREAL QC H3Z 2Y7
floor	The floor in an address, not a floor number in a unit (Brasilia only)	8o andar	SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
sector	The sector in an address (Brasilia only)	SBN	SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
quadrant	The quadrant in an address (Brasilia only)	Quadra 13	SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900
block	The block in an address (Brasilia only) the block in austria, singapore,... address	Bloca B 2	SBN - Quadra 13 - Bloca B - 8o andar BRASILIA-DF 70002-900 Rennbahnweg 25/2/15 1220 WIEN
lote	The lote in an address (Brasilia only)	LT 24	QE 32 CJ P LT 24 UND 2, BRASILIA, BR, 71065-161
country	The country name	USA United States France	Paris - France
countrycode	The countrycode given in the request	FR US DE	N/A
distance	The distance when an address is geocoded	3.251	N/A

Some other meta-data fields are aslo availables :

field	description	Examples of value
message	When informations need to be given	Contrycode XX is not implemented
qtime	Number of milisecond the request has taken	100
numFound	Number of results found	10

Confidence field

Parsing is a complex process. An address can sometimes be intrepreted in many ways and it is the parser job to find the best one. e.g : 'street of foo bar'=> we can not guess if foo bar is a city, or foo is a streetname and bar is a city
e.g : 'california st john'=> it can be california street at john city, or saint john in california.
e.g : 'rue de la gare de paris'=> it can be rue de la gare at Paris, or rue 'de la gare de paris'

The parser is designed to disambiguate address. The confidence just give an indicator on how the parser has got difficulties to parse the address. The confidence can take several values :

• MAX : the address has been parse without difficulties
• MEDIUM : some difficulties has been found but the parser found how to disambiguate
• MIN : some difficulties has been found and the parser failed to disambiguate

Note that only unit is supported, not company, gender, firstname, lastname. Mozilla Corporation, 1981 second street building K Mountain View CA 94043-0801 is not a parsable address, but 1981 second street building K Mountain View CA 94043-0801. A support is planed to split the first part of the address (to the first comma)

Batch processing

If you need to batch process a lot of data and don't want to buy the parser, we can batch process your addresses. The price depends of the ammount of data.

Some facilities are offered in the jar or the DLL. You can specify an AddressInput (file, memory, console, database,...) and an AddressOutput (file, memory, console,database,...). This makes it possible to read addresses from various sources and write them to other sources.
Example :

• Read addresses from a CSV file, add a column to the same (or different) file with the parsed address
• Read addresses from a database and put in the paresed addresses in memory (Map, List, whatever).

HTTP Connectors

The Java library can be embedded into your software, but can also be used as a REST webservice (hosted on your servers) via the address parser HTTPconnector. The webservice supports various output formats that eases the integration in your favorite language (PHP, RUBY, PYTHON, JSON/Javascript, YAML) but can also produce XML. This ensures that you can use it in any language, since you can do an HTTP request and parse XML or json.

Spoken languages supported

The parser is based on semantic analysis, it us some dictionary for street type, unit, ordinal number, etc... here is a list of already languages:

• English
• French (francais)
• Spanish (Español)
• German (Deutsch)
• Italian
• Portuguese
• Catalan (Català)
• Flemish (belgium dutch)
• Estonian (Eesti)
• Basque (Euskara) for France and Spain
• Russian (with Cyrillic alphabet)
• Polish
• Norwegian
• Turk
• Finnish
• Chinese (including chinese characters)
• Hungarian

An implemented language is a language that manage unit, street type, numbers, direction (cardinal point), Post Office Box, etc. Note that all the languages does not need all those type. If the dictionnary is not pertinent, the parser will fail for some parsing.

Implemented countries

Actually 70 are implemented. If you need a country that is not listed here, please contact us :

Algeria,  Angola,  American Samoa,  Argentina,  Aruba,  Australia,  Austria,  Belgium,  Bonaire, Saint eustatius and Saba,  Brazil,  Cameroon,  Canada,  China,  Congo (Democratic Republic of),  Curaçao,  Denmark,  Falkland Islands,  Faroe Islands, Finland,  France,  French Guiana,  Germany,  Guadeloupe,  Guernsey,  Gibraltar,  Greenland,  Hong Kong,  Hungary,  India,  Indonesia,  Iran,  Italy,  Isle of Man,  Jersey,  Kazakhstan,  Luxembourg,  Martinique,  Mexico,  Morocco,  Netherlands,  Netherlands Antilles,  Northern Mariana Islands,  Norway,  Puerto Rico,  Poland,  Portugal,  Reunion,  Russia,  Saint Helena,  Saint Martin,  Saint Pierre and Miquelon,  San Marino,  Saudi Arabia,  South Georgia and the South Sandwich Islands,  Senegal,  Singapore,  Sint Maarten,  Spain,  Sudan,  Sweden,  Switzerland,  Tunisia,  Turkey,  Turks and Caicos Islands,  Ukraine,  United States Minor Outlying Islands,  United Kingdom,  United States,  U.S. Virgin Islands,  Vatican, 

By continent : world | Africa | Asia | europe | middle east | south america

Countries not yet implemented

Here is a list of all unimplemented countries. that mean that the default pattern will be used. if you want a new country to be implemented, please contact us it can be implmented very quickly but it depends on the address complexity.

Aland Islands,  Albania,  Andorra,  Anguilla,  Antarctica,  Armenia,  Azerbaijan,  Bahamas,  Bahrain,  Bangladesh,  Barbados,  Belarus,  Belize,  Benin,  Bermuda,  Bhutan,  Bolivia,  Bosnia and Herzegovina,  Botswana,  Bouvet Island,  British Indian Ocean Territory,  British Virgin Islands,  Brunei,  Bulgaria,  Burkina Faso,  Burundi,  Cambodia,  Cameroon,  Cape Verde,  Cayman Islands,  Central African Republic,  Chad,  Chile,  Christmas Island,  Cocos Islands,  Colombia,  Comoros,  Cook Islands,  Costa Rica,  Croatia,  Cuba,  Cyprus,  Czech Republic,  Djibouti,  Dominica,  Dominican Republic,  East Timor,  Ecuador, ,  Egypt,  El Salvador,  Equatorial Guinea,  Eritrea,  Estonia,  Ethiopia,  Fiji,  French Polynesia,  French Southern Territories,  Gabon,  Gambia,  Georgia,  Ghana,  Greece,  Grenada,  Guam,  Guatemala,  Guinea,  Guinea-Bissau,  Guyana,  Haiti,  Heard Island and McDonald Islands,  Honduras,  Iceland,  Iraq,  Ireland,  *Israel,  Ivory Coast,  Jamaica,  *Japan,  Jordan,  Kenya,  Kiribati,  Kosovo,  Kuwait,  Kyrgyzstan,  Laos,  Latvia,  Lebanon,  Lesotho,  Liberia,  Libya,  Liechtenstein,  Lithuania,  Macao,  Macedonia,  Madagascar,  Malawi,  Malaysia,  Maldives,  Mali,  Malta,  Marshall Islands,  Mauritania,  Mauritius,  Mayotte,  Mexico,  Micronesia,  Moldova,  Monaco,  Mongolia,  Montenegro,  Montserrat,  Mozambique,  Myanmar,  Namibia,  Nauru,  Nepal,  New Caledonia,  New Zealand,  Nicaragua,  Niger,  Nigeria,  Niue,  Norfolk Island,  North Korea,  Oman,  Pakistan,  Palau,  Palestinian Territory,  Panama,  Papua New Guinea,  Paraguay,  Peru,  Philippines,  Pitcairn,  Qatar,  Republic of the Congo,  Romania,  Rwanda,  Saint Barthélemy,  Saint Kitts and Nevis,  Saint Lucia,  Saint Vincent and the Grenadines,  Samoa,  Sao Tome and Principe,  Serbia,  Serbia and Montenegro,  Seychelles,  Sierra Leone,  Slovakia,  Slovenia,  Solomon Islands,  Somalia,  South Africa,  South Korea,  Sri Lanka,  Suriname,  Svalbard and Jan Mayen,  Swaziland,  Syria,  Taiwan,  Tajikistan,  Tanzania,  Thailand,  Togo,  Tokelau,  Tonga,  Trinidad and Tobago,  Turkmenistan,  Tuvalu,  Uganda,  United Arab Emirates,  Uruguay,  Uzbekistan,  Vanuatu,  Venezuela,  Vietnam,  Wallis and Futuna,  Yemen,  Zambia,  Zimbabwe, 

Countries won't be implemented

Due to lack of informations, the following countries won't be implemented. it can be done with help of people living in this country :
Antigua and Barbuda,  Western Sahara,  Afghanistan, 

Supported formats by country

How to read the pattern: the words beetween braquet mean that this is optional. zip could also mean postal code. state could also mean province, and commonly represent an adminitrative division (full name or abbreviation), words beetween comma are necessary : e.g :

• (digit) means a number is required
• (,) means a comma is required
[top]

Algeria

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :APARTMENT N° 13 ENTRANCE C IMMEUBLE ANNADA 23 BOULEVARD DE LA MOSQUEE 16027 ALGIERS
• Special notes :
  • Arabic is not supported
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125/135
    • Example :125a
• Variant :
  • Type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName POBOX [unit] zip city [CEDEX [(number)]]
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 95190 Alger
      • pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city [CEDEX [(number)]]
      • Example :la poste de ma ville 157 bd du 3 février boite postale 52 95190 Alger cedex
      • pattern :POBOX [unit] [zip] city [CEDEX [(number)]]
      • Example :boite postale 52 box 5 95190 Alger cedex
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
    • Synonyms of boite postale are supported



[top]

American Samoa

See United States


[top]

Angola

• Typical address :
  • Pattern : streetType streetName [houseNumber|,] [[floor][side]] city
    • Example : Lg Dr António Viana 1 2 DTO 1250–096 LISBOA
    • Example : Rua Frederik Engels 92 – 7 o LUANDA
• Special notes :
  • There is no zipcode for Angola
  • if housenumber is not present a comma is necessary to separate streetname from city
  • side is optional and can be 'esq' or 'dto'
  • floor can be in various format (learn more
    • 13
    • 13º
    • 13°
    • c/v
    • r/c
    • 13º-D esq
• Variant :
  • Type : APARTADO (POBOX)
    • pattern : Apartado (number) city
    • Example : Apartado 42024 LUANDA
    • Synonyms of APARTADO are supported



[top]

Argentina

• Typical address :
  • Pattern : streetName houseNumber [unit] zip city
    • Example : Sarmiento 151 Piso 3 Oficina 311 BIS C1000ZAA BUENOS AIRES
• Special notes :
  • Special characters are supported
    • Example : é,í,º,ó,...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125a
  • Old postal code format is supported
    • Example :1419
• Variant :
  • Type : Casilla de Correo (POBOX)
    • Example : Casilla de Correo 432 Correo Central C1000WAM Capital Federal
    • Synonyms of Casilla de Correo are supported



[top]

Aruba

See Netherlands


[top]

Australia

• Typical address :
  • Pattern : [unit] [houseNumber] streetName streetType city province_abbreviation [zip]
    • Example : Level 7 17 Jones St. NORTH SYDNEY NSW 2060
• Special notes :
  • unit can be this form [Level number / apt number]
    • Example : 7 / 25 ADELAIDE ST BRISBANE CITY QLD 4000
  • If the street type is not present, put a comma before city
    • Example : 200 Broadway, WEST BEACH SA 5024
  • sometimes, street type is before the name, in this case a comma must be specified before city
    • Example : 200 street of americas, WEST BEACH SA 5024
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125a
• Variant :
  • Type : PO BOX
    • Example : PO BOX 37, SPRINGVALE VIC 3171
  • Synonyms for PO BOX are supported



[top]

Austria

• Typical address :
  • Pattern : streetName [streettype] houseNumber [unit] zip city
    • Example : Garten weg 8 Rafing 3741 PULKAU
• Special notes :
  • Special characters are supported
    • Example : ß(es-zett),ä,é,ü, ö, ...
  • Language is german
  • Zipcodes A-XXX is also supported
    • Example : Pazmaniteng 24-9 A-1020 Vienna
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125d
• Variant :
  • Type : Postfach (POBOX)
    • Example : Postfach 100 1011 WIEN
    • Example : Postlagernd 53131 Bonn
  • Synonyms for Postfach are supported



[top]

Belgium

• Typical address :
  • Pattern : streettype streetName houseNumber [unit] zip city
    • Example : Hoge Wei 27 B-1930 Zaventem
• Special notes :
  • language French and belgium are supported
    • Example : Rue du Cornet 6 4800 VERVIERS



[top]

Bonaire, Saint eustatius and Saba

See Netherlands


[top]

Brazil

• Typical address :
  • Pattern : streetType streetName [houseNumber|,] city-state [zip]
    • Example : Rua Visconde de Porto Seguro 1238 Sao Paulo-SP 04642-000
• Brasilia address :
  • Special portuguese characters are supported
    • Example : é,í,º,ó,...
  • Pattern : sector - quadra (digit) - block (a letter)- floor BRASILIA–DF zip
    • Example : SBNA - Quadra 13 - Bloca B - 18° andar BRASILIA-DF 70002-900
    • Example : QE 32 CJ P LT 24 UND 2, BRASILIA, BR, 71065-161
• Special notes :
  • city must be follow by a dash and the two letters state abbreviation
    • Example : Sao Paulo-SP
  • if house number is not specify, separate street name and city with a comma
    • Example : Rua Visconde de Porto Seguro, Sao Paulo-SP 04642-000
  • You can not specify citadel yet
    • Example : Sao Paulo-SP
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • Type : Caixa Postal (POBOX)
    • Example : APARTADO 1238 São Paulo - SP 04642-000
    • Synonyms of Caixa Postal are supported



[top]

Cameroun

We got lack of information for this country
• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] [,] streetName city
    • Example :12, rue foo YAOUNDE
• Special notes :
  • the comma beetween streetType and city is only required if the city contains space (<3%), it can be improved with a predifined list of cities that contains city
    • Example : Sandilands YAOUNDE : OK
    • Example : Sandilands, Afan Samabanga : OK
    • Example : Sandilands Afan Samabanga : KO (street=Sandilands Cheung)
  • Special characters are supported
    • Example : é,è,ç,ù...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName pobox [unit] city
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 YAOUNDE
      • pattern :[unit] [houseNumber] [streetType] streetName pobox city
      • Example :la poste de ma ville 157 bd du 3 février bp 52 YAOUNDE
      • pattern :pobox [unit] city
      • Example :boite postale 52 box 5 YAOUNDE
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us



[top]

Canada

• For all the pattern french and english are supported
• Typical address :
  • Pattern : [unit] [houseNumber] [fraction] [predirection] streetName streetType [postdirection] [unit] city [state] [zip]
    • Example : 123 3/4 N name with space 1 number blvd south floor 2 Missouri CA 12345-4536
    • Example : apt 10 123 smith street N Missouri
    • Example : 123 3/4 N name with space 1 number blvd south Missouri CA
• Variant
• Basic search are supported : streetName streetType City [state] [zip]
  • Example : art avenue new york
  • Note : If street type is before streetname (e.g : street of amercia), A comma is necessary before city
• Type : city [state] [zip]
  • Example : saint louis BC 12345-4536
  • Example : saint louis british columbia 12345-4536
  • Example : saint louis BC
  • Example : saint louis 12345-4536
  • Example : saint louis
  • Note : No check is made. if you put any string it will be considered as city.
• Type : ordinal [streetType] city [state] [zip]
  • Example : 8th, V3X 1K1
  • Example : 8th saint louis
  • Example : 8th Avenue, saint louis
  • Example : 8th Avenue, saint louis bc V3X 1K1
  • Example : 8th, saint louis bc 63101
  • Note : A comma is necessary before city
• Street intersection : [houseNumber] [predirection] streetName streetType [postdirection] [unit] city [state] [zip] & [houseNumber] [predirection] streetName streetType [postdirection] [unit] city [state] [zip]
  • The separator beetween two street is '&'
  • Example : N name 1 with and in name1 street & W name 2 boulevard E Missouri
  • Example : 18th & W name 2 boulevard Missouri
• Street type before name : [houseNumber] [fraction] [predirection] streetType streetName [postdirection] [unit] city [state] [zip]
  • Example : 500 E street of america SUITE 5A TUCSON AZ 85705
  • Tips : it will help the parser to have a comma before city,because we can not spearate streetname and city acuratly
• Type : PO BOX, Pattern : [houseNumber] [fraction] [POBOX or synonyms] number [STN|RPO] [(a letter)] [unit] city [state] [zip]
  • Example : 1425 JAMES ST PO BOX 4001 STN A VICTORIA BC V8X 3X4
  • Synonyms for PO BOX are supported
    • POB,POBX,POBX,...
• Special notes :
  • All the element can be in french or english, an address can mix both language but it is not recommended
    • Example (en): 500 E street of america room 5A TUCSON AZ 85705
    • Example (fr): 500 E rue des ameriques chambre 5A TUCSON AZ 85705
    • Example (en+fr): 500 E rue des ameriques chambre 5A TUCSON AZ 85705
  • State can be abbreviation or full name
    • Example : saint louis BC
    • Example : saint louis British Columbia
  • Unit can be this form [unit unitMember | unitMember unit]
    • Example : apt 4, 5th floor, HANGAR 8, room
    • Tips : unit is based on dictionary, if it fails we can add some words, just send us a mail
  • If the street type is not present, put a comma before city
    • Example : 200 18th, UCSON AZ 85705
  • General delivery (poste restante) are not supported
  • We can not list all the possible patterns, but many others are supported



[top]

China

Chinese address can be specify in chinese (Simplified or Traditional) or in roman script.
• Typical address :
  • Pattern : [unit] [houseNumber] streetName [streetType] city [zip] [province]
    • Example : ROOM 305 63 RENMIN LU, QINGDAO SHI 266033 SHANDONG
    • Example : 87/F Jiu Shi Fu Xin Mansion 36 BAOSHAN JIUCUN, BAOSHAN DISTRICT 201900 SHANGHAI
    • Note : a comma is necessary to separate streetname and City, if not we can not separate the district of the street name
    • Note : The province will be fill in the state field
• Variant
• Direct controlled municipality
  • Pattern : [unit] [houseNumber] streetName [streetType] District|County [zip] [Direct controlled municipality]
  • Example : 36 BAOSHAN JIUCUN, BAOSHAN DISTRICT 201900 SHANGHAI
  • Note : The Direct controlled municipality will be fill in the state and city field
  • Note: defunct municipalities are managed as state
• Other patterns
  • Pattern : [houseNumber] [unit] streetName [streetType] District|County [city] [zip]
  • Example : 1 BUILDING TIME MALL YIHUA ROAD MEIZHOU 514021
  • Pattern : [unit] [houseNumber] streetName [streetType] District|County [city] [zip]
  • Example : BUILDING 15 5 RENMIN W RD FUXING DISTRICT HANDAN 056003
• Special notes :
  • Chinese symbols are fully supported (county, direct municipality, province, street intersection,...):
    • An address written in Chinese will start with the biggest geographical component (the province) and end with the smallest one (the addressee)
    • Pattern : Direct controlled municipality|province [prefectures] [District|County]streetName [streetType] [houseNumber] [unit]
    • Example : 北京市朝阳区望京阜通东大街阜荣街东亚望京中心A座一层商铺
    • Example : 安徽福州市庐阳区广顺南大街东亚望京中心A座层商铺
    • The same Chinese address written in the Roman (Latin) alphabet, the format will be used from the smallest geographical component at the top to the biggest at the bottom.
    • Even if the postal system is based on Wade–Giles romanization, Complete diacritic, accent marks and special characters are supported : Yáohǎi or Yaohai will both be detected. Learn more on Chinese Postal Map Romanization
  • Rural route and General delivery (poste restante) are not supported



[top]

Congo (Democratic Republic of)

We got lack of information for this country
• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] [,] streetName city
    • Example :12, rue Kakamoueka BRAZZAVILLE
• Special notes :
  • the comma beetween streetType and city is only required if the city contains space (<3%), it can be improved with a predifined list of cities that contains city
    • Example : Sandilands BRAZZAVILLE : OK
    • Example : Sandilands, Yoko Yaolonga : OK
    • Example : Sandilands Yoko Yaolonga : KO (street=Sandilands Cheung)
  • Special characters are supported
    • Example : é,è,ç,ù...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName pobox [unit] city
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 BRAZZAVILLE
      • pattern :[unit] [houseNumber] [streetType] streetName pobox city
      • Example :la poste de ma ville 157 bd du 3 février bp 52 BRAZZAVILLE
      • pattern :pobox [unit] city
      • Example :boite postale 52 box 5 BRAZZAVILLE
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
    • Synonyms of POBOX are supported



[top]

Curaçao

See Netherlands


[top]

Denmark

• Typical address :
  • Pattern : streetName [houseNumber] [unit] [district] zip [city]
    • Example : Kastanievej 15, 2 Agerskov 1566 COPENHAGEN V
    • Example : Niels Bohrs Alle 23, room 45 district 5230 Odense M
• Special notes :
  • special char : Æ,Ø,Å are managed
  • unit can be of various form (in english): floor number, stage, room, ...
    • Example : 3
    • Example : floor 3
  • Zip can be this form DK-#### or ##### where '#' is a digit
• Variant :
  • Type : Postboks (POBOX)
    • Pattern : Postboks (digit) zip [city]
    • Example : Postboks 321 8660 SKANDERBORG
    • Note : It is a basic pattern that can be improved, but due to lack of informations,for now, only the pattern above is implemented
    • Synonyms of Postboks are supported



[top]

Falkland Islands

See United kingdom




[top]

Faroe islands

See Denmark


[top]

Finland

• Typical address :
  • Pattern :streetName [houseNumber] [unit] [zip] city
    • Example :Mäkelänkatu 25 B 13 FI-00550 HELSINKI
• Special notes :
  • Zip with format 'FI-XXXXX'an 'XXXXX' are supported
  • Special characters are supported
    • Example : å,ä,ö,...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-126
    • Example :125c
• Variant :
  • Type : PL (Pobox)
    • • pattern :POBOX [POBOX AGENCY] zip city
      • Example :PL 447 Sentrum FI-00550 HELSINKI
      • Example :PL 447 FI-00550 HELSINKI
    • Synonyms of POBOX are supported



[top]

France

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :caserne des pompiers étage 2 palier 3 157 bd du 3 juillet étage n°2 95190 saint jean de luz
• Special notes :
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • Lieu dit after street name is not supported
    • Example :25 RUE DE L EGLISE Lieu dit 33380 maville
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName POBOX [unit] zip city [CEDEX [(number)]]
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 95190 saint jean de luz cedex
      • pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city [CEDEX [(number)]]
      • Example :la poste de ma ville 157 bd du 3 février boite postale 52 95190 saint jean de luz cedex
      • pattern :POBOX [unit] [zip] city [CEDEX [(number)]]
      • Example :boite postale 52 box 5 95190 saint jean de luz cedex
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
    • Synonyms of boite postale are supported



[top]

French guiana

See France




[top]

Germany

• Typical address :
  • Pattern : streetName [streettype] houseNumber[/number|letter] [unit] zip city
    • Example : Rhondorfer Str. 665 Appartment 47 50939 Köln
• Special notes :
  • Special characters are supported
    • Example : ß(es-zett),ä,é,ü, ö, ...
  • Packstation is not supported
    • Example : 1234567 Packstation 101 53113 Bonn
  • HouseNumber can be a range
    • Example :125-132
  • HouseNumber can be slashed or follow by numbers+letter, in this case the part after the first number will be consider as apartment or suite number
    • Example :125/126(126 will be the apartment number, so will be part of the extra information)
    • Example :125 A(a will be the suite letter, so will be part of the extra information)
  • Street name can have minus in name
    • Example :Döner-Strasse will be a streetname
    • Example :Döner Strassewill be a streetName and streetType
• Variant :
  • Type : Postfach (POBOX)
    • Example : Postfach 3 41 41 10724 Berlin
    • Synonyms of Postfach are supported
  • number/block/flat
    • Example : Rennbahnweg 25/2/15 1220 WIEN



[top]

Gibraltar

See United Kingdom


[top]

Greenland

See Denmark


[top]

Guernsey

See United Kingdom


[top]

India

As the Universal postal union says : "There is no clear advice on how to format an address correctly ". So a specific implementation has been made for india. The confidence is always 'MIN' for india
• Special notes :
  • Indian address can have the following components (all are facultative) whatever the order, that's allow a very flexible syntax
    • Street name then type : main road, 1st A street, foo road,...
    • Cross Street name then cross : 1st Cross, 1st A cross,...
    • House number (at the beginning) : 125, #562, new # 265,...
    • Block, phase, stage, sector, floor, unit member : , 3rd block, 4 block, 2nd stage,4th sector,Phase 3,Gopalan Mall ground floor
    • zipcode560 035, 560035
    • city (before zip and after comma)bangalore
    • state (after zip)manipur
• Typical address :
  • pattern [unit wherever in address] [house number] [street name (cross and main or single road)] + [area name with block/phase/stage/sector) city name + postcode + [stateName]
    • Example : New #5, 1st Cross, HSR Layout,80th Feet Main Road Phase 3, 4th sector, 51st block, 2nd stage,bangalore 560 035 manipur
    • Example : New #768, Ground Floor, 100 Feet Road, 12th Main Road, HAL 2nd Stage bangalore 560 035 Chamba-Kangra



[top]

Indonesia

I have implemented the Universal postal union specifications and the specifications found on Wikipedia. it is not easy to find THE pattern on indonesian address format, so feel free to contact us if you got more informations on indonesian address format
• Typical address :
  • Pattern : [HouseNumber] streetName streetType [houseNumber] city|regencies [zip] province/state
    • Example : 73 Jalan Cilaki, BANDUNG 40115 Sulbar
    • Example : Jalan Cilaki 73 BANDUNG 40115 Sulbar
• Special notes :
  • Indonesian provinces is a defined list (in indonesian,sundanese, english, abbreviation,...) the parsing can fail if a state is not present in this list. contact us if you think a province is missing
  • HouseNumber can be before (as Universal postal union says) or after street name (as Wikipedia and a lot of site says)
  • if house number is before streettype, a comma can help to distinguish streetname from cities, but is not required
    • Example : 73 Jalan Cilaki, BANDUNG 40115 Sulbar
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125/132
    • Example :125-126
    • Example :125a



[top]

Iran

I have implemented the Universal postal union specifications but no information are available on the Iran site and a lot of site gives alternative patterns , so feel free to contact us if you got more informations on Iran address format
• Typical address :
  • Pattern : streetName streetType|(,) [houseNumber] [unit] [zip] city
    • Example : Shahid Hossein Behrouz street No 17 1st floor 1193653471 TEHRAN
  • Pattern for Posttown : City [,village] [,unit/building] streetName(,) [houseNumber] [unit] [zip] Postown
    • Example : Amirieh, Farhang, Shahid Hossein Behrouz, Alavi lased No 17 1st floor 1193653471 TEHRAN
  • The City, village (when present) and building(when present) Must be be separated by comma
• Special notes :
  • if streettype is not present, a comma is necessary after the street name
    • Example : Shahid Hossein Behrouz, No 17 TEHRAN
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125/132
    • Example :125-126
    • Example :125a
• Variant :
  • Type : PO BOX
    • Pattern : PO BOX zip city
    • Example : P.O. Box 16315-336 1631481654 TEHRAN
  • Synonyms for PO BOX are supported



[top]

Italy

• Typical address :
  • Pattern :[unit] [streetType] streetName [houseNumber] [zip] city [state]
    • Example :VIALE EUROPA 22 00144 ROMA RM
    • Example :Strada Statale 27 56 00144 ROMA RM
• Special notes : for All patterns, zip can be before or after city, state is optional.
• HouseNumber can be a range or slashed or numbers+letter
  • Example :125-132, 125/3
• Kilometric civic number is not supported yet
  • Example :VIA CARDANO KM 1,234
• Special attention has been made for Autostrada, tunnel, Strada statale, Strada regionale, Strada provinciale,...
  • Example : A13, T5, SS406, SR46,..
• Variant :
  • type : CASELLA POSTALE (POBOX)
    • Pattern :[unit] POBOX [zip] city [state]
    • Example :UFFICIO ROMA TRULLO CASELLA POSTALE 1234 00149 ROMA RM
  • Synonyms of CASELLA POSTALE are supported
  • type : CASELLA POSTALE (POBOX)
    • Pattern :[unit] [streetType] streetName [houseNumber] [zip] city [state]
    • Example :appartamento 2 CORSO SEMPIONE 94 MILANO 20154
    • Pattern :[unit] [houseNumber] [streetType] streetName [zip] city [state]
    • Example :appartamento 2 94 CORSO SEMPIONE MILANO 20154

Isle of Man

See United Kingdom

Guadeloupe

See France

Hong Kong

• Typical address :
  • Pattern : [unit] [houseNumber] streetName [streetType] city|district [hong kong[NT]]
    • Example : 16 Sandilands Road WAN CHAI
  • Pattern : [houseNumber] streetName streetType [unit] city|district [hong kong[NT|new territories]]
    • Example : 150 Kennedy Road great Towers Aberdeen
• Special notes :
  • Street type is optionnal but strongly recommended
  • hong kong will be populated in state field
  • There is no zipcode in hongkong
  • If the street type is not present, the city will be considered as the last word, if it is not the case put a comma
    • Example : Sandilands Aberdeen : OK
    • Example : Sandilands, Cheung Chau : OK
    • Example : Sandilands Cheung Chau : KO (street=Sandilands Cheung)
  • Sometimes, street type is before the name, in this case a comma must be specified before city
    • Example : street of Sandilands, Aberdeen
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125/132
    • Example :125-126
    • Example :125a
• Variant :
  • Type : PO BOX
    • Pattern : POBOX [Po box agency]
    • Example : P.O. Box 42345 CAUSEWAY BAY POST OFFICE
  • Synonyms for PO BOX are supported

Turks and Caicos Islands

See United Kingdom

Hungary

• Typical address :
  • Pattern : city streetName [streettype] [houseNumber] [unit] [zip]
    • Example : BUDAPEST VIRÁG TÉR 3. IV. 61 1037
  • Pattern : zip city streetName [streettype] [houseNumber] [unit]
    • Example : 1037 BUDAPEST VIRÁG TÉR 3. IV. 61
• Special notes :
  • Special characters are supported
  • HouseNumber can be a range or a number with a letter or slashed
    • Example :125-126
    • Example :125/126
    • Example :125c
• Variant :
  • Type : postafiók (PO BOX)
    • Pattern : [city] postafiók [zip]
    • Example : Budapest Pf. 184 2806
    • Synonyms of postafiók are supported

Jersey

See United Kingdom

Kazakhstan

See Russia

Martinique

See France

Moroco

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :APARTMENT N° 13 ENTRANCE C IMMEUBLE ANNADA 23 BOULEVARD TAROUDANT 52000 ERRACHIDIA
• Special notes :
  • Arabic is note supported
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • Lieu dit after street name is not supported
    • Example :25 RUE DE LA MOSQUEE Lieu dit 33380 maville
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125/135
    • Example :125a
• Variant :
  • Type : boite postale (PoBox)
    • • Pattern :[unit] streetType streetName POBOX [unit] zip city [CEDEX [(number)]]
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 52000 ERRACHIDIA cedex
      • Pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city [CEDEX [(number)]]
      • Example :la poste de ma ville 157 bd du 3 février boite postale 52 52000 ERRACHIDIA cedex
      • Pattern :POBOX [unit] [zip] city [CEDEX [(number)]]
      • Example :boite postale 52 box 5 52000 ERRACHIDIA cedex
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
    • Synonyms of boite postale are supported

Turks and Caicos Islands

See United Kingdom

Netherlands

• Typical address :
  • Pattern : streetName [houseNumber] [zip] city
    • Example : Surinamestraat 27 2585 GJ Den Haag
• Special notes :
  • Special characters are supported
  • zip can be ommited only if there is no housenumber (pattern streetname + city), if not the parser can be confused
  • HouseNumber can be a range or a number with a letter or slashed
    • Example :125-126
    • Example :125/126
    • Example :125c
  • if you only put streetname and city (without zip and housenumber), the last word will be considered as the city, if the city is composed, separate the streetname and the city by a comma
    • Example :alexandrastraat amsterdam, amsterdamwill be the city
    • Example :alexandrastraat the hague, 'hague' will be the city
    • Example :alexandrastraat, the hague, 'the hague' will be the city
• Variant :
  • Type : Postbus (PO BOX)
    • Example : P.O. Box 24024 2490 AA THE HAGUE
    • Example : postbus 24024 2554 FG 's-GRAVENHAAG
    • Synonyms of Postbus are supported

Netherlands Antilles

See Netherlands

Northern Mariana Islands

See United States

Norway

• Typical address :
  • Pattern :streetName [houseNumber] [unit] [zip] city
    • Example :Passion 21 b 6415 Bergan
    • Example :Passion 21 first floor 6415 Bergan
• Special notes :
  • Zip with format 'NO-XXXX' and 'XXXX' are supported
  • Special characters are supported
    • Example : å,ä,ö,...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-126
    • Example :125c
• Variant :
  • Type : Postboks (Pobox)
    • • pattern :POBOX [POBOX AGENCY] zip city
      • Example :Postboks 447 Sentrum 0104 OSLO
      • Example :Postboks 447 0104 OSLO
    • Synonyms of Postboks are supported

Puerto Rico

See United States

Poland

• Typical address :
  • Pattern :[streetType] streetName [houseNumber] [(/)flatnumber] [dependentLocality] [zip] city
    • Example :ul. Asfaltowa 2/3 Rudzienko 05–470 KOLBIEL
• Special notes :
  • Special characters are supported
    • Example : dź,ś,ł,ą...
  • flat number will be populated in extra info
  • HouseNumber can not be a range but can end with a letter
    • Example :125c
• Variant :
  • type : Skrytka pocztowa (POBOX)
    • pattern :pobox zip city
    • Example :Skrytka pocztowa 115 48–300 NYSA
    • Poste restante:(poste restante) zip city
    • Example :Poste restante 32–015 KLAJ
    • Synonyms of Skrytka pocztowa are supported
    • pattern :[houseNumber] [streetType] streetName city [zip]
    • Example :4 STANISLAWA DOMARASIEWICZA SKIERNIEWICE 96-106

Portugal

• Typical address :
  • Pattern : streetType streetName [houseNumber|,] [[floor][side]] [zip] city
    • Example : Lg Dr António Viana 1 2 DTO 1250–096 LISBOA
    • Example : Lg Dr António Viana LISBOA
• Typical address :
  • Pattern : streetType streetName [houseNumber|,] [[floor][side]] [city] [zip] [posttown]
    • Example : R. Leal da Camara 31 RL ESQ ALGUEIRÃO 2725–079 MEM MARTINS
• Special notes :
  • if housenumber and zip is not present a comma is necessary to separate streetname from city
  • side is optional and can be 'esq' or 'dto'
  • floor can be in various format (learn more
    • 13
    • 13º
    • 13°
    • c/v
    • r/c
    • 13º-D esq
• Variant :
  • Type : APARTADO (POBOX)
    • pattern : Apartado (number) [POBOXInfo] zip city
    • Example : Apartado 42024 EC – D. LUÍS 1201–950 LISBOA
    • Example : Apartado 42024 1201–950 LISBOA
  • Synonyms of POBOX are supported

Reunion

See france

Russia

• Typical address :
  • Pattern : [StreetType] streetName HouseNumber [unit] City [District] [OBLAST|KRAY|RESPUBLIKA] [country] [zip] [country]
    • Example : ул. Ореховая, д. 25 пос. Лесное АЛЕКСЕЕВСКИЙ р-н ВОРОНЕЖСКАЯ обл. РОССИЙСКАЯ ФЕДЕРАЦИЯ 247112
    • Example : ул. Ореховая, д. 25 пос. Лесное АЛЕКСЕЕВСКИЙ р-н ВОРОНЕЖСКАЯ обл. 247112, RUSSIAN FEDERATION
    • Example : ул. Лесная, д. 5, кв. 176 г. МОСКВА РОССИЙСКАЯ ФЕДЕРАЦИЯ 125075
  • when District and province(OBLAST/KRAY/RESPUBLIKA) are present, the designator should be specify
    • Example : АЛЕКСЕЕВСКИЙ р-н is valid but not АЛЕКСЕЕВСКИЙ
    • Example : ВОРОНЕЖСКАЯ обл. is valid but not ВОРОНЕЖСКАЯ
    • Synonyms and abbreviation are supported in both alphabets : Oblast, Област, obl, обл, Raion, Раион, r-n, р-н, ...
  • Country can be before or after zipcode
  • Only russian language is supported, not english. If you need english, contact us
  • both alphabet are supported
  • Country can be "RUSSIAN FEDERATION" or "РОССИЙСКАЯ ФЕДЕРАЦИЯ" or "RUSSIA"
  • The universal postal union recommand to reserve the last line for country, but we support the recommandation from the The russian Post)
  • Street type before name : streetName [StreetType] HouseNumber [unit] City [District] [OBLAST|KRAY|RESPUBLIKA] [country] [zip] [country]
    • Example : Большая Никитская улица, д. 25 пос. Лесное Лесное АЛЕКСЕЕВСКИЙ р-н ВОРОНЕЖСКАЯ обл. РОССИЙСКАЯ ФЕДЕРАЦИЯ 247112
• POBOX
  • Pattern : Zip city POBOX
  • Example : 125167, г.Москва, а/я 1-А
  • Pattern : POBOX city zip
  • Example : Абон.ящ. № 3749, Днепропетровск, 01055
  • Synonyms for POBOX are supported in both alhabet (Абоне́нтский я́щик,...)
• Special notes :
  • Cyrilic Alphabet is fully supported
    • Example : Oblast is equivalent to Област
  • Abbreviation are supported
    • Example : Ulica == Улица == Ул == Ул. == ul == ul., ...

Saint Helena

See United Kingdom

Saint Martin

See france

Saint Pierre and Miquelon

See france

San Marino

See Italy

Saudi arabia

• Typical address :
  • Pattern : [houseNumber] streetName streetType city [zip]
    • Example : 8228 King Abdulaziz Rd RIYADH 12643
  • Pattern : POBOX city [zip]
    • Example : P.O. Box 56577 RIYADH 11564
  • Synonyms of POBOX are supported
• Special notes :
  • zip can be simple (e.g : 12345) or extended (e.g : 12345-6789)
  • arabian language is not yet supported

Senegal

See France

Singapore

• Typical address :
  • Pattern : [unit] [houseNumber] streetName [streetType] city [zip]
    • Example : 16 Sandilands Road SINGAPORE 546080
  • Pattern : [block] [houseNumber] streetName [streetType] [unit] city [zip]
    • Example : Blk 35 Mandalay Road # 13–37 Mandalay Towers SINGAPORE 308215
• Special notes :
  • Street type is optionnal but strongly recommended
  • unit can be this form (#) (digit)-(digit) strings
    • Example : # 13–37 Mandalay Towers
  • If the street type is not present, the city will be considered as the last word, if it is not the case put a comma
    • Example : Sandilands, SINGAPORE 546080 : OK
    • Example : Sandilands, SINGAPORE with space 546080 : OK
    • Example : Sandilands SINGAPORE with space 546080 : KO (street=Sandilands SINGAPORE with)
  • sometimes, street type is before the name, in this case a comma must be specified before city
    • Example : street of Sandilands, SINGAPORE 546080
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125/132
    • Example :125-126
    • Example :125a
• Variant :
  • Type : PO BOX
    • Pattern : PO BOX city [zip]
    • Example : PO BOX 37, SINGAPORE 546080
  • Synonyms for PO BOX are supported

Sint Maarten

See Netherlands

South Georgia and the South Sandwich Islands

See United Kingdom

Spain

• Typical address :
  • Pattern : [streetType] streetName [No] houseNumber [unit] zip city [state]
    • Example : Calle Sarmiento 151 Piso 3 Oficina 311 BIS 39012 Palma de Majorque (Baleares)
• Special notes :
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125/126
    • Example :125a
• Variant :
  • Type : Apartado Correos (POBOX)
    • Example : Apartado Correos 396, Malaga
    • Example : Apartado Correos 396, 08013 Barcelona
  • Synonyms of POBOX are supported
  • Type : [unit] [houseNumber] [streettype] streetname city [zip] [state]
    • Example : piso 4 82 Avenida de Canillejas a Vicalvaro MADRID 28022
  • Type : [unit] [houseNumber] [streettype] streetname zip city [state]
    • Example : piso 4 82 Avenida de Canillejas a Vicalvaro 2802 MADRID
  • Type : [streettype] streetname [houseNumber] [unit] city [zip] [state]
    • Example : Avenida de Canillejas a Vicalvaro 82 apt 2 MADRID 2802
  • Type : [streettype] streetname [houseNumber] [unit] zip city [state]
    • Example : Avenida de Canillejas a Vicalvaro 82 apt 2 2802 MADRID
  • S/N (aka sin número) is supported
  • City, state and zip can be specified in any order. Unit can be specified at the beginning or after houseNumber

France

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :caserne des pompiers étage 2 palier 3 157 bd du 3 juillet étage n°2 95190 saint jean de luz
• Special notes :
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • Lieu dit after street name is not supported
    • Example :25 RUE DE L EGLISE Lieu dit 33380 maville
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName POBOX [unit] zip city [CEDEX [(number)]]
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 95190 saint jean de luz cedex
      • pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city [CEDEX [(number)]]
      • Example :la poste de ma ville 157 bd du 3 février boite postale 52 95190 saint jean de luz cedex
      • pattern :POBOX [unit] [zip] city [CEDEX [(number)]]
      • Example :boite postale 52 box 5 95190 saint jean de luz cedex
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
  • Synonyms of boite postale are supported

Sudan

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :Immeuble de la fraternité 3 Rue Al-Comhouriya 11111 KHARTOUM
• Special notes :
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • Lieu dit after street name is not supported
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • type : boite postale (POBOX)
    • • pattern :[unit] streetType streetName POBOX [unit] zip city
      • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 11111 KHARTOUM
      • pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city
      • Example :la poste de ma ville 157 bd du 3 février boite postale 52 11111 KHARTOUM
      • pattern :POBOX [unit] [zip] city
      • Example :boite postale 52 box 5 11111 KHARTOUM
      • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
  • Synonyms of boite postale are supported

Sweden

• Typical address :
  • Pattern :streetName [houseNumber] [unit] [zip] city
    • Example :NYBY 10 123 45 LILLBYN
• Special notes :
  • Zip with format 'SE-XXX XX' is supported
  • Special characters are supported
    • Example : å,ä,ö,...
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-126
    • Example :125c
• Variant :
  • Type : POBOX
    • • pattern :POBOX [zip] [city]
      • Example :Box 1237, 131 28 Nacka Strand
      • Example :Box 1237
    • Synonyms of POBOX are supported

Switzerland

• German and French is supported
• Typical address :
  • Pattern in German: streetName [streettype] houseNumber[/number|letter] [unit] zip city
    • Example : Rhondorfer Str. 665 Appartment 47 9876 Tihidorf
  • Pattern in French: streettype streetName houseNumber[/number|letter] [unit] zip city
    • Example : Rue de bourgogne 665, Appartement 47 9876 Tihidorf
• Special notes :
  • Special characters are supported
    • Example : ß(es-zett),ä,é,ü, ö, ...
  • Packstation is not yet supported
    • Example : 1234567 Packstation 101 53113 Bonn
  • HouseNumber can be a range
    • Example :125-132
  • HouseNumber can be slashed or follow by numbers+letter, in this case the part after the first number will be consider as apartment or suite number
    • Example :125/126(126 will be the apartment number, so will be part of the extra information)
    • Example :125 A(a will be the suite letter, so will be part of the extra information)
  • Street name can have minus in name
    • Example :Döner-Strasse will be a streetname
    • Example :Döner Strassewill be a streetName and streetType
• Variant :
  • Type : Postfach, Case postale (PO BOX). In german, french and english.
    • Example : Postfach 3 41 41 10724 Berlin
    • Example : Rue de Bourgogne 15 Case postale 230 9876 Tihidorf
    • Example : Zichzachweg 15 Case postale 230 9876 Tihidorf
    • Example : P.O. Box 21
  • Synonyms for PO BOX are supported in both alhabet

Turkey

• Typical address :
  • Pattern :[quater] streetName streetType [houseNumber] [(/)extra number info] [zip] [district] city
    • Example :DOĞANBEY MAH. EHİTTEĞMENKALMAZ CAD. NO: 2/311 06101 ALTINDAĞ/ANKARA
• POSTA ABONE KUTUSU (PO BOX) :
  • pattern :[POBOX INFO] POBOX zip [district] city
  • Example :ULUS PTT MERKEZİ PK 543 06040 ULUS/ANKARA
  • Synonyms of POSTA ABONE KUTUSU are supported
• Special notes :
• Special characters are supported
  • Example : Ğ,Ş,ü...

Tunisia

• Typical address :
  • Pattern :[unit] [houseNumber] [streetType] streetName [zip|,] city [CEDEX [(number)]]
    • Example :étage 2 palier 3 157 AVENUE DE LA LIBERTE 1002 TUNIS BELVEDERE
• Special notes :
  • Special characters are supported
    • Example : é,è,ç,ù...
  • If zipcode is not present, a comma must be present before city
  • Lieu dit after street name is not supported
    • Example :25 RUE DE L EGALITE Lieu dit 3338 maville
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125c
• Variant :
  • Type : boite postale (POBOX)
    • pattern :[unit] streetType streetName POBOX [unit] zip city [CEDEX [(number)]]
    • Example :la poste de ma ville bd du 3 février boite postale 52 box 3 8129 AIN DRAHAM cedex
    • pattern :[unit] [houseNumber] [streetType] streetName POBOX zip city [CEDEX [(number)]]
    • Example :la poste de ma ville 157 bd du 3 février boite postale 52 8129 AIN DRAHAM cedex
    • pattern :POBOX [unit] [zip] city [CEDEX [(number)]]
    • Example :BOITE PRIVEE 52 box 5 8129 AIN DRAHAM cedex
    • Note : it might exist some 'boite postale' patterns that are not managed, feel free to contact us
  • Synonyms of boite postale are supported

Ukraine

• Typical address :
  • Pattern : [StreetType] streetName HouseNumber [unit] City [District] [OBLAST|KRAY|RESPUBLIKA] [zip]
    • Example : Vul. Lisova, 2, kv.3 s. Ivanovka, Semenivsky r-n, TCHERNIGIVSKA OBL.15432
    • Example : ul. Astronomicheskaya 22, kv. 33 Kharkov 12345
  • when District and province(OBLAST/KRAY/RESPUBLIKA) are present, the designator should be specify
    • Example : АЛЕКСЕЕВСКИЙ р-н is valid but not АЛЕКСЕЕВСКИЙ
    • Example : ВОРОНЕЖСКАЯ обл. is valid but not ВОРОНЕЖСКАЯ
    • Synonyms and abbreviation are supported in both alphabets : Oblast, Област, obl, обл, Raion, Раион, r-n, р-н, ...
  • Street type before name : streetName [StreetType] HouseNumber [unit] City [District] [OBLAST|KRAY|RESPUBLIKA] [zip]
    • Example : Большая Никитская улица, д. 25 пос. Лесное Лесное АЛЕКСЕЕВСКИЙ р-н ВОРОНЕЖСКАЯ обл. 01055
• Type : PO BOX
  • Pattern : Zip city POBOX
  • Example : 125167, г.Москва, а/я 1-А
  • Oter pattern : POBOX city zip
  • Example : Абон.ящ. № 3749, Днепропетровск, 01055
  • Synonyms for PO BOX are supported in both alphabet (Абоне́нтский я́щик,...)

Special notes :

• Cyrilic Alphabet is fully supported for all address components
  • Example : Oblast is equivalent to Област
• Abbreviation are supported
  • Example : Ulica == Улица == Ул == Ул. == ul == ul., ...

United States Minor Outlying Islands

See United States

United Kingdom

• Typical address :
  • Pattern : [unit] [houseNumber] streetName streetType city [Postown] [Shire] [zip]
    • Example : room 105 6 Oxford Road Hedle End SOUTHAMPTON HP19 3EQ
• Special notes :
  • Double dependent locality is not managed
    • Example : 1 Upper Littleton Winford BRISTOL BS18 8HF
  • Postown is a predifined list, if a parsing fails, it can be a missing ones. Please contact us
    • Example : 200 Broadway, WEST BEACH SA 5024
  • Unit can not start with number (too ambiguous with houseNumber
    • Example : in 2b Barry Jackson Tower Estone Walk BIRMINGHAM B6 5BA, the 2B will be treat as houseNumber
  • HouseNumber can be a range or slashed or numbers+letter
    • Example :125-132
    • Example :125-126
    • Example :125a
• Variant :
  • Type : POBOX
    • Example : 100 MAIN ST P.O.Box 136
    • Synonyms of POBOX are supported

United States

• Typical address :
  • Pattern : [houseNumber] [fraction] [predirection] streetName [streetType] [postdirection] [unit] city [state] [zip]
    • Example : 123 3/4 N name with space 1 number blvd south floor 2 Missouri CA 12345-4536
    • Example : 123 3/4 N name with space 1 number blvd south Missouri CA
  • Zip and zip+4, street type abbreviation, number as letter, direction abbreviation, many common usages are supported

• Basic search are supported : streetName [streetType] City [state] [zip]
  • Example : art avenue new york
• If street type is before streetname (e.g : street of amercia), A comma before city can give better confidence
• Streettype is optional but STRONGLY recommended

• Type :city [state] [zip]
  • Example : saint louis al 63101
  • Example : saint louis alabama 63101
  • Example : saint louis al
  • Example : saint louis 63101
  • Example : saint louis
• No check is made. if you put any string it will be considered as city.
• state can be abbreviation or full name

• Type :ordinal [streetType] city [state] [zip]
  • Example : 8th saint louis
  • Example : 8th Avenue, saint louis
  • Example : 8th Avenue, saint louis al 63101
  • Example : 8th, saint louis al 63101
• Tips : it will help, (but not necessary) the parser to have a comma before city if street type is not provided.

• Street intersection : [houseNumber] [predirection] streetName streetType [postdirection] [unit] city [state] [zip] & [houseNumber] [predirection] streetName streetType [postdirection] [unit] city [state] [zip]
  • The separator beetween two street is '&'
  • Example : N name 1 with and in name1 street & W name 2 boulevard E Missouri
  • Example : 18th & W name 2 boulevard Missouri

• Rural route and county road
• example : 2315 COUNTY ROAD 6643, BANKS AL 36005
• example : rural route 8 box 24 andalusia al 36420

• Street type before name : [houseNumber] [fraction] [predirection] streetType streetName [postdirection] [unit] city [state] [zip]
  • Example : 500 E street of america SUITE 5A TUCSON AZ 85705
  • Tips : it will help the parser to have a comma before city, because we can not spearate streetname and city acuratly

• We can not list all the possible patterns, but many others are supported

• Type : PO BOX
  • Example : 100 MAIN ST PO BOX 1022 SEATTLE WA 98104
  • Example : P.O. Box 36647 - 1CR
  • Example : P.O. Box 21
• Synonyms for PO BOX are supported
  • POB,POBX,POBX,PMB...

Special notes :

• Only English language is supported, not spanish (in some city, spanish is sometimes used due to inhabitant).
• State can be abbreviation or full name
  • Example : saint louis al 63101
  • Example : saint louis alabama 63101

• unit can be this form [unit unitMember | unitMember unit]
  • Example : apt 4, 5th floor, HANGAR 8, room
  • Tips : unit is based on dictionary, if it fails we can add some words, just send us a mail
• If the street type is not present, put a comma before city
  • Example : 200 18th, UCSON AZ 85705

U.S. Virgin Islands

See United States

Vatican

See Italy

known issues

• city with unit member (lake:AMBROSIA LAKE park:SANDIA PARK, ...) in name, can confuse the parser. It is specially the case in Australia and great britain (e.g : wilbertree flat in australia)
• ' (Simple quote) is not kept in parsing results (reason: serialisation in json ...)

Links

• http://www.upu.int/
• http://auspost.com.au/business/address-matching-approval-system.html
• http://www.canadapost.ca/cpo/mc/business/productsservices/atoz/addressingsoftware.jsf
• http://www.envmgr.com/site/company/cass_cert.htm