API

The LibPostal API

This wiki page serves to be a reference for the usage of the LibPostal API.

Initialisers (The Setup)

Before LibPostals functions can be used, the library must be initialised. LibPostal requires it's core to be initialised first followed by the modules you wish to use.

The LibPostal Core

bool libpostal_setup(void);

• return bool: Whether the operation was a success.

This will initialise LibPostal using the default directory set at compile time.

bool libpostal_setup_datadir(char *datadir);

• return bool: Whether the operation was a success.
• char *datadir: The directory from which to load LibPostal.

This will initialise LibPostal using the directory specified within the datadir variable.

The LibPostal Address Parser

bool libpostal_setup_parser(void);

• return bool: Whether the operation was a success.

This will initialise LibPostals Address Parser using the default directory set at compile time.

bool libpostal_setup_parser_datadir(char *datadir);

• return bool: Whether the operation was a success.
• char *datadir: The directory from which to load LibPostal.

This will initialise LibPostals Address Parser using the directory specified within the datadir variable.

The LibPostal Language Classifier

bool libpostal_setup_language_classifier(void);

• return bool: Whether the operation was a success.

This will initialise LibPostals Language Classifier using the default directory set at compile time.

bool libpostal_setup_language_classifier_datadir(char *datadir);

• return bool: Whether the operation was a success.
• char *datadir: The directory from which to load LibPostal.

This will initialise LibPostals Language Classifier using the directory specified within the datadir variable.

Destructors (The Tear Down)

These free up the resources used by LibPostals modules.

The LibPostal Core

void libpostal_teardown(void);

The LibPostal Address Parser

void libpostal_teardown_parser(void);

The LibPostal Language Classifier

void libpostal_teardown_language_classifier(void);

Address Expansion

Before using the Address Expansion, you must initialize the Language Classifier (see Initialisers).

Config

libpostal_normalize_options_t libpostal_get_default_options(void);

• return libpostal_normalize_options_t: #ToDo

Action

char **libpostal_expand_address(char *input, libpostal_normalize_options_t options, size_t *n);

• return char **: #ToDo

char **libpostal_expand_address_root(char *input, libpostal_normalize_options_t options, size_t *n);

• return char **: #ToDo

Clean Up

void libpostal_expansion_array_destroy(char **expansions, size_t n);

Address Parser

Before using the Address Parser, you must initialize the Address Parser (see Initialisers).

Config

libpostal_address_parser_options_t libpostal_get_address_parser_default_options(void);

• return libpostal_address_parser_options_t: #ToDo

Action

libpostal_address_parser_response_t *libpostal_parse_address(char *address, libpostal_address_parser_options_t options);

• return libpostal_address_parser_response_t *: #ToDo

Clean Up

void libpostal_address_parser_response_destroy(libpostal_address_parser_response_t *self);

Duplicate Classification (?)

#ToDo: Write Description

Config

libpostal_near_dupe_hash_options_t libpostal_get_near_dupe_hash_default_options(void);

• return libpostal_near_dupe_hash_options_t: #ToDo

Action

char **libpostal_near_dupe_hashes(size_t num_components, char **labels, char **values, libpostal_near_dupe_hash_options_t options, size_t *num_hashes);

• return char **: #ToDo

char **libpostal_near_dupe_hashes_languages(size_t num_components, char **labels, char **values, libpostal_near_dupe_hash_options_t options, size_t num_languages, char **languages, size_t *num_hashes);

• return char **: #ToDo

char **libpostal_place_languages(size_t num_components, char **labels, char **values, size_t *num_languages);

• return char **: #ToDo

Address Matching

ToDo: Write Description

Config

libpostal_duplicate_options_t libpostal_get_default_duplicate_options(void);

• return libpostal_duplicate_options_t: #ToDo

libpostal_duplicate_options_t libpostal_get_duplicate_options_with_languages(size_t num_languages, char **languages);

• return libpostal_duplicate_options_t: #ToDo

Action

libpostal_duplicate_status_t libpostal_is_name_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_street_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_house_number_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_po_box_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_unit_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_floor_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_postal_code_duplicate(char *value1, char *value2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

libpostal_duplicate_status_t libpostal_is_toponym_duplicate(size_t num_components1, char **labels1, char **values1, size_t num_components2, char **labels2, char **values2, libpostal_duplicate_options_t options);

• return libpostal_duplicate_status_t: #ToDo

Fuzzy Matching

ToDo: Write Description

Config

libpostal_fuzzy_duplicate_options_t libpostal_get_default_fuzzy_duplicate_options(void);

• return libpostal_fuzzy_duplicate_options_t: #ToDo

libpostal_fuzzy_duplicate_options_t libpostal_get_default_fuzzy_duplicate_options_with_languages(size_t num_languages, char **languages);

• return libpostal_fuzzy_duplicate_options_t: #ToDo

Action

libpostal_fuzzy_duplicate_status_t libpostal_is_name_duplicate_fuzzy(size_t num_tokens1, char **tokens1, double *token_scores1, size_t num_tokens2, char **tokens2, double *token_scores2, libpostal_fuzzy_duplicate_options_t options);

• return libpostal_fuzzy_duplicate_status_t: #ToDo

libpostal_fuzzy_duplicate_status_t libpostal_is_street_duplicate_fuzzy(size_t num_tokens1, char **tokens1, double *token_scores1, size_t num_tokens2, char **tokens2, double *token_scores2, libpostal_fuzzy_duplicate_options_t options);

• return libpostal_fuzzy_duplicate_status_t: #ToDo

Normalization

ToDo: Write Description

libpostal_token_t *libpostal_tokenize(char *input, bool whitespace, size_t *n);

• return libpostal_token_t *: #ToDo

char *libpostal_normalize_string(char *input, uint64_t options);

• return char *: #ToDo

char *libpostal_normalize_string_languages(char *input, uint64_t options, size_t num_languages, char **languages);

• return char *: #ToDo

libpostal_normalized_token_t *libpostal_normalized_tokens(char *input, uint64_t string_options, uint64_t token_options, bool whitespace, size_t *n);

• return libpostal_normalized_token_t *: #ToDo

libpostal_normalized_token_t *libpostal_normalized_tokens_languages(char *input, uint64_t string_options, uint64_t token_options, bool whitespace, size_t num_languages, char **languages, size_t *n);

• return libpostal_normalized_token_t *: #ToDo

Debug Features

These functions are used for debuging features within LibPostal. They are not needed for normal operation.

bool libpostal_parser_print_features(bool print_features);

• return bool: #ToDo
• bool print_features: This switches the feature on or off.

When switched on this will cause the LibPostal Address Parser to print debug information to stdout (The Console).