Getting Started

from deepparse.parser import AddressParser
from deepparse.dataset_container import CSVDatasetContainer

address_parser = AddressParser(model_type="bpemb", device=0)

# you can parse one address
parsed_address = address_parser("350 rue des Lilas Ouest Québec Québec G1L 1B6")

# or multiple addresses
parsed_address = address_parser(["350 rue des Lilas Ouest Québec Québec G1L 1B6",
     "350 rue des Lilas Ouest Québec Québec G1L 1B6"])

# or multinational addresses
# Canada, US, Germany, UK and South Korea
parsed_address = address_parser(
    ["350 rue des Lilas Ouest Québec Québec G1L 1B6", "777 Brockton Avenue, Abington MA 2351",
     "Ansgarstr. 4, Wallenhorst, 49134", "221 B Baker Street", "서울특별시 종로구 사직로3길 23"])

# you can also get the probability of the predicted tags
parsed_address = address_parser("350 rue des Lilas Ouest Québec Québec G1L 1B6",
     with_prob=True)

# Print the parsed address
print(parsed_address)

# or using one of our dataset container
addresses_to_parse = CSVDatasetContainer("./a_path.csv", column_names=["address_column_name"],
                                         is_training_container=False)
address_parser(addresses_to_parse)

The default predictions tags are the following

  • "StreetNumber": for the street number,

  • "StreetName": for the name of the street,

  • "Unit": for the unit (such as apartment),

  • "Municipality": for the municipality,

  • "Province": for the province or local region,

  • "PostalCode": for the postal code,

  • "Orientation": for the street orientation (e.g. west, east),

  • "GeneralDelivery": for other delivery information.

Parse Addresses From the Command Line

You can also use our cli to parse addresses using:

parse <parsing_model> <dataset_path> <export_file_name>

Parse Addresses Using Your Own Retrained Model

See here for a complete example.

address_parser = AddressParser(
    model_type="bpemb", device=0, path_to_retrained_model="path/to/retrained/bpemb/model.p")

address_parser("350 rue des Lilas Ouest Québec Québec G1L 1B6")

Retrain a Model

See here for a complete example using Pickle and here for a complete example using CSV.

address_parser.retrain(training_container, train_ratio=0.8, epochs=5, batch_size=8)

One can also freeze some layers to speed up the training using the layers_to_freeze parameter.

address_parser.retrain(training_container, train_ratio=0.8, epochs=5, batch_size=8, layers_to_freeze="seq2seq")

Or you can also give a specific name to the retrained model. This name will be use as the model name (for print and class name) when reloading it.

address_parser.retrain(training_container, train_ratio=0.8, epochs=5, batch_size=8, name_of_the_retrain_parser="MyNewParser")

Retrain a Model With an Attention Mechanism

See here for a complete example.

# We will retrain the fasttext version of our pretrained model.
address_parser = AddressParser(model_type="fasttext", device=0, attention_mechanism=True)

address_parser.retrain(training_container, train_ratio=0.8, epochs=5, batch_size=8)

Retrain a Model With New Tags

See here for a complete example.

address_components = {"ATag":0, "AnotherTag": 1, "EOS": 2}
address_parser.retrain(training_container, train_ratio=0.8, epochs=1, batch_size=128, prediction_tags=address_components)

Retrain a Seq2Seq Model From Scratch

See here for a complete example.

seq2seq_params = {"encoder_hidden_size": 512, "decoder_hidden_size": 512}
address_parser.retrain(training_container, train_ratio=0.8, epochs=1, batch_size=128, seq2seq_params=seq2seq_params)

Download Our Models

Deepparse handles model downloads when you use it, but you can also pre-download our model. Here are the URLs to download our pretrained models directly

Or you can use our CLI to download our pretrained models directly using:

download_model <model_name>

Note on FastText Models

Deepparse reads the FastText embeddings with its own reader of the .bin format, which gives the same vectors as the fasttext package. It does not need fasttext nor gensim, so the FastText models work the same way on every supported Python version. The embeddings matrix is memory-mapped: it loads in a few seconds and the data loading workers share its memory.

FastText parser (CPU)

Former loading (gensim)

Memory-mapped reader (after 0.11.0)

Loading time

~42 s

~4 s

RAM after loading

~8.4 GB

~1.2 GB

Peak RAM

~13.2 GB

~1.3 GB

The RAM is the whole process (Torch and the model included), measured while parsing 10,000 addresses (Linux, Python 3.12, CPU).

The BPEmb embeddings, which are much smaller, are also loaded without gensim after version 0.11.0: they load in ~0.2 s instead of ~0.9 s and take ~0.14 GB of RAM instead of ~0.26 GB.