README
¶
address-parser-go
Shared address parsing library: normalizes free-form street names (Russian) to canonical street records with confidence scoring.
Extracted from 005-bot/monitor-go
(internal/parser/address) and published as a standalone Go module for reuse.
Features
- Embedded SQLite street database (
streets.db, loaded via pure-Gomodernc.org/sqlite, no CGO required). - Exact-match lookup with confidence
1.0. - Fuzzy matching: Levenshtein similarity + LCS blend (
0.3/0.7), minimum confidence0.6, minimum LCS coverage of the stored name0.4. - Input cleaning: lowercase, strip punctuation (Unicode
[^\p{L}\p{N}\s\-]), collapse whitespace. fxmodule integration (address.Module()).
API
type Config struct { DBPath string }- optional path to an external streets DB (uses embedded copy when empty).NewParser(cfg Config) (*Parser, error)- load streets into memory.(*Parser).Normalize(ctx context.Context, raw string) (*Match, error)- match raw input to a street.(*Parser).Stop()- release temp resources (embedded DB extraction dir).type Match struct { Name string; NormalizedName string; Confidence float64 }.var ErrNoMatch- returned when no street scores at least0.6.
Usage
package main
import (
"context"
"fmt"
"github.com/005-bot/address-parser-go"
)
func main() {
p, err := address.NewParser(address.Config{})
if err != nil {
panic(err)
}
defer p.Stop()
m, err := p.Normalize(context.Background(), "ул. Ленина")
if err != nil {
panic(err)
}
fmt.Printf("%s (%.2f)\n", m.Name, m.Confidence)
// улица Ленина (1.00)
}
As an fx module:
import "github.com/005-bot/address-parser-go"
app := fx.New(
address.Module(),
fx.Provide(func() address.Config { return address.Config{} }),
)
Development
make test- race-enabled tests with coverage.CGO_ENABLED=0 go build ./...- pure-Go build (verified).make lint- golangci-lint.
Attribution
- Parser code extracted from 005-bot/monitor-go
(
internal/parser/address), Apache-2.0. streets.dbfrom 005-bot/address-parser, Apache-2.0; byte-identical to the Python address-parser database (MD510072cee7eb84361125cbdaf76559093).- Fuzzy scoring (edlib Levenshtein + LCS blend) intentionally differs from the
Python
difflibscores; exact matches produce identical results.
License
Apache-2.0 - see LICENSE.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoMatch = errors.New("no matching street found")
ErrNoMatch is returned by Normalize when no street reaches the minimum confidence threshold.
Functions ¶
Types ¶
type Config ¶
type Config struct {
DBPath string `koanf:"db_path"`
}
Config controls parser initialization. DBPath optionally points to an external SQLite streets database; when empty, the embedded copy is used.
type Match ¶
type Match struct {
// Name is the canonical street name as stored in the database.
Name string `json:"name"`
// NormalizedName is the lowercased form used for lookups.
NormalizedName string `json:"normalized_name"`
// Confidence is the match score; 1.0 for exact matches.
Confidence float64 `json:"confidence"`
}
Match is a resolved street with a confidence score in [0, 1].
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser matches free-form street names against an in-memory street index. It is safe for concurrent use.
func NewParser ¶
NewParser loads streets into memory and returns a ready-to-use Parser. When cfg.DBPath is empty, the embedded street database is extracted to a temporary directory; call Stop to release it. On failure the temporary directory is removed before returning.
func (*Parser) Normalize ¶
Normalize matches rawInput against the street index and returns the best match. Exact matches have confidence 1.0; otherwise a weighted blend of Levenshtein similarity and LCS is used, requiring at least 0.6 confidence and 0.4 LCS coverage of the stored name. Returns ErrNoMatch when nothing scores high enough, or a context error when ctx is canceled.
Source Files