onecontactDocs
onecontact docs
Everything about OneContact 1.0: getting started, phones, email and web addresses, postal addresses country by country, names and companies, extraction from pages and text, and the model packages that follow in 1.1.
Start
Getting startedInstall OneContact 1.0.0 for .NET 10, then validate and format a phone number, check an email address, parse a web address, read a postal address and pull the contacts out of a small web page. Every sample on this page was run on the 1.0.0 packages from NuGet and shows its…Overviewlibphonenumber- and libpostal-class contact data for .NET.All notesStart with the README for the packages, the quick start and the results. Documents about the trained model packages are marked from 1.1. Coming from another library? Read migrating.md first. The rest of this folder is ordered the way you will probably need it. Documents…Coming from another libraryThree reads-like tables for people who know the libraries OneContact replaces. Each row names a call or concept from the other library's published documentation and the OneContact call that does the same job. There is no compatibility layer and no copied API shape: OneContact…Parse overloads, reasons and JSON
Phones
Phone numbersNormative notes for the phone core. Public API: PhoneNumber (value type) and PhoneNumberParser (engine with explicit PhoneMetadata) in RecursiveAI.OneContact.Phones.Geocoder, carrier and time zonesNormative notes for RecursiveAI.OneContact.Phones.Geo: the geocoder, the carrier mapper and the time-zone mapper for phone numbers. The package references the core library only and carries its own compiled tables; the core library stays free of this data.
Email and web addresses
Email addressesEmailAddress reads one mailbox: an addr-spec (jane@example.com) or a name-addr (Jane Doe ), and gives a canonical form, a versioned key, flags and offsets into the input. EmailParser is the low-level form (span in, OperationStatus and ParseDetail out, plus a batch form).Web addressesWebAddress parses a website address with the WHATWG URL Standard and reports a canonical form, a comparison key, facts and offsets. Everything here is written from the URL Standard (living standard, last updated 19 October 2026), UTS #46, RFC 3492 and the Public Suffix List's…The Public Suffix ListRecursiveAI.OneContact.Web.PublicSuffixList answers two questions about a domain name: its public suffix and its registrable domain.Internationalized domain namesInternationalized host names go through Unicode IDNA Compatibility Processing (UTS #46, non-transitional) the way the URL Standard asks for. Everything is in src/OneContact/Text/Idna.
Postal addresses
The structural layer, every countryWhat the library knows about the shape of an address in every country the address data describes: which fields exist, in what order they are written, which are required, what a postal code looks like, and which subdivisions a country lists. It is data plus a small engine. It…United States and CanadaHow a free-text United States or Canadian address is read, standardized and rendered. The code is RuleAddressParser (reading), StreetLineParser (one delivery line), AddressRenderer (the postal and display styles) and AddressExpander / AddressKey (expansion and key). The rules…France, Benelux, Germany, Austria, SwitzerlandHow the rule parser (Addresses/Tier2) reads and standardizes these addresses. The rules are data (Addresses/Data/T2/*.tsv) plus one reader; adding a country of this kind means adding rows. The sources are the postal authorities' free public guides, listed at the end. Paid…Britain, Ireland, Iberia, Italy, MaltaHow the rule parser (Addresses/Tier2) reads and standardizes these addresses. They are rows in the same tables as the first Tier 2 group (Addresses/Data/T2/*.tsv), read by the same reader; docs/address-rules-tier2-a.md describes the shared parts. This page lists what is…Nordic and Baltic countriesHow the rule parser (Addresses/Tier2) reads and standardizes these addresses. They are rows in tables of their own (Addresses/Data/T2/*-north.tsv), read by the same reader as the other Tier 2 countries; docs/address-rules-tier2-a.md and -b.md describe the shared parts. This…Central Europe, Mexico, AustraliaHow the rule parser (Addresses/Tier2) reads and standardizes these addresses. They are rows in the same tables as the earlier Tier 2 groups (Addresses/Data/T2/*-c-south.tsv, read next to the base files), read by the same reader (Tier2Reader.Central.cs holds what is particular…The last line, country by countryThe authorities' sheets print the postcode and the locality in one order per country (docs/address-rules-tier2-*.md). Web pages write other orders. The rule reader accepts them when the country is known (a hint or a country name in the text), rearranges the lines in memory so…When the country can’t be toldMany postcodes are written alike in several countries: four digits in Belgium, Austria, Switzerland, Liechtenstein, Luxembourg, Denmark, Norway, Slovenia and Hungary; five in France, Germany, Spain, Italy, Croatia, Mexico, Finland, Estonia, Lithuania and Sweden. When a text…Expansion dictionariesThe expansion of an address (AddressExpander) and the words of its key use the dictionary files of libpostal (MIT licence), ingested from pinned data files by tools/Ingest.LibPostalDictionaries. Only the files named in upstream/libpostal-dictionaries/PIN are used: English and…The address keyPostalAddress.Key, GetKey(KeyVersion.V1) and AddressKey.Compute give the key. A published version's output never changes: a rule change ships as a new KeyVersion with its own golden fixtures (testdata/addresses/key-v1-golden.tsv holds version 1's).
Names and companies
Person namesRules only. PersonName, NameParsing.Classify/Split/SplitMany and NameHints read a string, give every part with offsets into the input (UTF-16 chars), and say in ParseDetail which issues were met. Nothing is inferred: no gender, origin or salutation, and no part is added that…The person keyPersonKey.Compute(PersonName, KeyVersion) and PersonName.Key give the aggressive, versioned comparison key. Canonical forms stay faithful; only the key loses information. A published version's output never changes: a rule change ships as a new KeyVersion with its own golden…Company names and legal formsCompanyName and CompanyNameParser read a company name into: leading article ("The"), base name, legal form (with its ISO 20275 ELF code and a canonical abbreviation), "trading as" part and "c/o" part. Every part carries offsets into the input. Rules only; the legal form comes…
Models (from 1.1)
How the models plug inThe Tier 1 + Tier 2 package RecursiveAI.OneContact.Models is described in models-superset.md.The Tier 1 + Tier 2 packageThe same design as the Tier 1 package (see models.md): one fast-tier encoder shared by an address-field head, a name-part head, a name-class head and a contact-span head, trained with OneNLP's Train on OneModel. It covers the United States, Canada and every Tier 2 country.…The accurate tierRecursiveAI.OneContact.Models.Accurate is the opt-in model package for harder text. It carries the same four heads as the fast tier on one frozen encoder: OneNLP's distilled multilingual student (RecursiveAI.OneNlp.Models.Multilingual.FrozenEncoder, six layers, width 384, 113…Training data: United States and CanadaHow the examples for the address-field head are made, what a line looks like, and what the labels mean. The tool is tools/data/AddressUsCa; where the data comes from and its licences are in tools/data/provenance/address-us-ca.md.Training data: Tier 2, group AHow the examples for the address-field head are made for these countries, and what is different from the United States and Canada (docs/training-data-address-us-ca.md, whose file format and label names this follows). The tool is tools/data/AddressTier2A; registers, licences…Training data: Tier 2, group BHow the examples for the address-field head are made for these countries. The file format, label names, splits and determinism are those of the other address tools (docs/training-data-address-us-ca.md, docs/training-data-address-tier2-a.md); this note covers what differs. The…Training data: Tier 2, group CHow the examples for the address-field head are made for these countries. File format, label names, splits and determinism are those of docs/training-data-address-tier2-a.md; this page says what differs. The tool is tools/data/AddressTier2C (it shares the tokenizer, random…Training data: the challenger modelHow the examples for a challenger address-field model are made from the OpenStreetMap address file of the published libpostal parser training set. The file format, tokens and span rules are those of the other address tools (docs/training-data-address-us-ca.md); this note…
Inside the library
ArchitectureNormative notes on how the code and its data fit together. Behaviour of each contact kind (key rules, rendering rules, label schemes) gets its own document here when the code for it lands.Tools and data directoriesThe scripts and tools under tools/, recipes/ and bench/ keep everything large outside the repository. Each location is an environment variable with a default under ~/onecontact/; nothing in the repository names a machine or a private folder.ChangelogAll notable changes are recorded here. The format follows Keep a Changelog, and versions follow Semantic Versioning.