geocoder

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 23, 2022 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Census geocoder.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var DefaultBenchmark = "Public_AR_Current"

Default benchmark ID.

View Source 
var DefaultClient = Client{Url: DefaultUrl}

Default client.

View Source 
var DefaultUrl = &net_url.URL{
	Scheme: "https",
	Host:   "geocoding.geo.census.gov",
	Path:   "/geocoder/",
}

Default Census geocoder URL.

Functions

This section is empty.

Types

type BatchInputReader 

type BatchInputReader struct {
	// contains filtered or unexported fields
}

Batch geocode CSV reader

func NewBatchInputReader 

func NewBatchInputReader(r io.Reader) BatchInputReader

Create batch CSV reader.

func (BatchInputReader) ReadAll 

func (me BatchInputReader) ReadAll() ([]BatchInputRow, error)

Parse all rows in CSV as BatchInputRow items.

Note: The first row of the CSV file is *not* skipped, so if it contains column headers it should be removed.

type BatchInputRow 

type BatchInputRow struct {
	// Unique row ID (required)
	Id string

	// street address (required)
	Address string

	// city
	City string

	// state
	State string

	// zip code
	Zip string
}

Row of input batch CSV.

type BatchInputWriter 

type BatchInputWriter struct {
	// contains filtered or unexported fields
}

func NewBatchInputWriter 

func NewBatchInputWriter(w io.Writer) BatchInputWriter

func (BatchInputWriter) WriteAll 

func (me BatchInputWriter) WriteAll(rows []BatchInputRow) error

type BatchOutputReader 

type BatchOutputReader struct {
	// contains filtered or unexported fields
}

Batch geocode output CSV reader

func NewBatchOutputReader 

func NewBatchOutputReader(r io.Reader) BatchOutputReader

Create batch CSV reader.

func (BatchOutputReader) ReadAll 

func (me BatchOutputReader) ReadAll() ([]BatchOutputRow, error)

Parse CSV rows as BatchOutputRow items.

type BatchOutputRow 

type BatchOutputRow struct {
	// unique row ID
	Id string `json:"id"`

	// source address
	InputAddress string `json:"input_address"`

	// was this input row matched?
	Match bool `json:"is_match"`

	// is address an exact match?
	Exact bool `json:"is_exact"`

	// normalized matched address
	MatchAddress string `json:"match_address"`

	// lat/long
	Coordinates Coordinates `json:"coordinates"`

	// tiger line data
	TigerLine TigerLine `json:"tigerLine"`

	// State ID (only populated if `returntype = geographies`).
	State string

	// County ID (only populated if `returntype = geographies`).
	County string

	// tract (only populated if `returntype = geographies`).
	Tract string

	// block ID (only populated if `returntype = geographies`).
	Block string
}

Batch geocoder output row.

func BatchGeographies 

func BatchGeographies(rows []BatchInputRow, benchmark, vintage string) ([]BatchOutputRow, error)

Batch geocode street addresses with given benchmark and vintage using default client, then return matches with additional geography fields.

The additional BatchOutputRow fields populated by this function compared to `BatchLocationsFromBenchmark()` are as follows:

- State - County - Tract - Block

func BatchLocations 

func BatchLocations(rows []BatchInputRow) ([]BatchOutputRow, error)

Batch geocode street addresses using default client then return matches.

func BatchLocationsFromBenchmark 

func BatchLocationsFromBenchmark(rows []BatchInputRow, benchmark string) ([]BatchOutputRow, error)

Batch geocode street addresses with given benchmark using default client then return matches.

func NewBatchOutputRow 

func NewBatchOutputRow(row []string) (BatchOutputRow, error)

Create batch output row from CSV row.

type Benchmark 

type Benchmark struct {
	// Vintage ID
	Id string `json:"id"`

	// Vintage name
	Name string `json:"benchmarkName"`

	// Vintage description
	Description string `json:"benchmarkDescription"`

	// Is this the default vintage?
	Default bool `json:"isDefault"`
}

Benchmark from Benchmarks()

func Benchmarks 

func Benchmarks() ([]Benchmark, error)

Get benchmarks from default client.

Example 
// get benchmarks
benchmarks, err := Benchmarks()
if err != nil {
	log.Fatal(err)
}

// print benchmark names to standard output
for _, b := range benchmarks {
	fmt.Println(b.Name)
}

Output:
Public_AR_Current
Public_AR_ACS2022
Public_AR_Census2020

type Client added in v0.2.0 

type Client struct {
	// base API URL
	Url *net_url.URL

	// shared HTTP client
	Client http.Client
}

Census geocoder client.

func NewClient added in v0.2.0 

func NewClient(url *net_url.URL) Client

Create new geocoder client from URL.

Note: This method is primarily for testing. You should be able to use the top-level functions from the geocoder package (e.g. geocoder.Locations, geocoder.Geographies, etc).

func (Client) BatchGeographies added in v0.2.0 

func (c Client) BatchGeographies(rows []BatchInputRow, benchmark, vintage string) ([]BatchOutputRow, error)

Batch geocode street addresses with given benchmark and vintage then return matches with additional geography fields.

The additional BatchOutputRow fields populated by this method compared to `BatchLocationsFromBenchmark()` are as follows:

- State - County - Tract - Block

func (Client) BatchLocations added in v0.2.0 

func (c Client) BatchLocations(rows []BatchInputRow) ([]BatchOutputRow, error)

Batch geocode street addresses then return matches.

func (Client) BatchLocationsFromBenchmark added in v0.2.0 

func (c Client) BatchLocationsFromBenchmark(rows []BatchInputRow, benchmark string) ([]BatchOutputRow, error)

Batch geocode street addresses with given benchmark then return matches.

func (Client) Benchmarks added in v0.2.0 

func (c Client) Benchmarks() ([]Benchmark, error)

Get available benchmarks.

Example 
// create client using default URL
c := NewClient(DefaultUrl)

// get benchmarks
benchmarks, err := c.Benchmarks()
if err != nil {
	log.Fatal(err)
}

// print benchmark names to standard output
for _, b := range benchmarks {
	fmt.Println(b.Name)
}

Output:
Public_AR_Current
Public_AR_ACS2022
Public_AR_Census2020

func (Client) Geographies added in v0.2.0 

func (c Client) Geographies(address, benchmark, vintage string) ([]Match, error)

Geocode street address using given benchmark and given vintage, then return address matches with geography layers.

Example 
// create client using default URL
c := NewClient(DefaultUrl)

// get address matches with additional geographical information
locs, err := c.Geographies("3444 gallows rd annandale va 22003", "2020", "2020")
if err != nil {
	log.Fatal(err)
}

// print matched addresses to standard output
for _, v := range locs {
	cbsaName := v.Geographies["Combined Statistical Areas"][0]["NAME"]
	fmt.Printf("%s - %s\n", v.MatchedAddress, cbsaName)
}

Output:
3444 GALLOWS RD, ANNANDALE, VA, 22003 - Washington-Baltimore-Arlington, DC-MD-VA-WV-PA CSA

func (Client) Locations added in v0.2.0 

func (c Client) Locations(address string) ([]Match, error)

Geocode street address and return address matches.

Example 
// create client using default URL
c := NewClient(DefaultUrl)

// get address matches
locs, err := c.Locations("3444 gallows rd annandale va 22003")
if err != nil {
	log.Fatal(err)
}

// print matched addresses to standard output
for _, v := range locs {
	fmt.Println(v.MatchedAddress)
}

Output:
3444 GALLOWS RD, ANNANDALE, VA, 22003

func (Client) LocationsFromBenchmark added in v0.2.0 

func (c Client) LocationsFromBenchmark(address, benchmarkId string) ([]Match, error)

Geocode street address with given benchmark ID return address matches.

func (Client) Vintages added in v0.2.0 

func (c Client) Vintages(benchmarkId string) ([]Vintage, error)

Get vintages matching benchmark ID.

Example 
// create client using default URL
c := NewClient(DefaultUrl)

// get vintages
vintages, err := c.Vintages("2020")
if err != nil {
	log.Fatal(err)
}

// print vintage names to standard output
for _, v := range vintages {
	fmt.Println(v.Name)
}

Output:
Census2020_Census2020
Census2010_Census2020

type Coordinates 

type Coordinates struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

lat/long coordinates.

func NewCoordinates 

func NewCoordinates(s string) (Coordinates, error)

Create coordinates from input string

type Match added in v0.3.0 

type Match struct {
	// tiger data
	TigerLine TigerLine `json:"tigerLine"`

	// latitude and longitude
	Coordinates Coordinates `json:"coordinates"`

	// matched components
	AddressComponents struct {
		// zip code
		Zip string `json:"zip"`

		// street name
		StreetName string `json:"streetName"`

		// street prefix type
		PreType string `json:"preType"`

		// city
		City string `json:"city"`

		// prefix direction
		PreDirection string `json:"preDirection"`

		// suffix direction
		SuffixDirection string `json:"suffixDirection"`

		// from address
		FromAddress string `json:"fromAddress"`

		// state
		State string `json:"state"`

		// suffix type
		SuffixType string `json:"suffixType"`

		// to address
		ToAddress string `json:"toAddress"`

		// suffix qualifier
		SuffixQualifier string `json:"suffixQualifier"`

		// prefix qualifier
		PreQualifier string `json:"preQualifier"`
	} `json:"addressComponents"`

	// matched address
	MatchedAddress string `json:"matchedAddress"`

	// map of ID to geography components.
	//
	// Note: only populated for calls to `Geographies()`.
	Geographies map[string][]map[string]any `json:"geographies"`
}

Address match result from [Locations()] or [Geographies()].

func Geographies 

func Geographies(address, benchmark, vintage string) ([]Match, error)

Geocode street address using default client, given benchmark, and given vintage, then return address matches with geography layers.

Example 
// get address matches with additional geographical information
locs, err := Geographies("3444 gallows rd annandale va 22003", "2020", "2020")
if err != nil {
	log.Fatal(err)
}

// print matched addresses to standard output
for _, v := range locs {
	cbsaName := v.Geographies["Combined Statistical Areas"][0]["NAME"]
	fmt.Printf("%s - %s\n", v.MatchedAddress, cbsaName)
}

Output:
3444 GALLOWS RD, ANNANDALE, VA, 22003 - Washington-Baltimore-Arlington, DC-MD-VA-WV-PA CSA

func Locations 

func Locations(address string) ([]Match, error)

Geocode street address using default client and return address matches.

Example 
// get address matches
locs, err := Locations("3444 gallows rd annandale va 22003")
if err != nil {
	log.Fatal(err)
}

// print matched addresses to standard output
for _, v := range locs {
	fmt.Println(v.MatchedAddress)
}

Output:
3444 GALLOWS RD, ANNANDALE, VA, 22003

func LocationsFromBenchmark 

func LocationsFromBenchmark(address, benchmarkId string) ([]Match, error)

Geocode street address with given benchmark ID using default client and return address matches.

type TigerLine 

type TigerLine struct {
	// Line ID
	Id string `json:"tigerLineId"`

	// Line side
	Side string `json:"side"`
}

type Vintage 

type Vintage struct {
	Id          string `json:"id"`
	Name        string `json:"vintageName"`
	Description string `json:"vintageDescription"`
	Default     bool   `json:"isDefault"`
}

Vintage from Vintages().

func Vintages 

func Vintages(benchmarkId string) ([]Vintage, error)

Get vintages matching benchmark ID from default client.

Example 
// get vintages
vintages, err := Vintages("2020")
if err != nil {
	log.Fatal(err)
}

// print vintage names to standard output
for _, v := range vintages {
	fmt.Println(v.Name)
}

Output:
Census2020_Census2020
Census2010_Census2020

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.