Address Parser Go REST

https://pkg.go.dev/github.com/gosom/address-parser-go-rest
Admin
Address Parser Go REST is a REST API that provides address parsing functionality using the libpostal...
Tokens:4,135
Snippets:43
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Address Parser Go REST with Docker

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

Use this command to quickly start the Address Parser Go REST service using Docker. Ensure Docker is installed and running.

```bash
docker run -p 8080:8080 gosom/address-parser-go-rest
```

--------------------------------

### Run Address Parser Go REST Without Docker

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

Steps to install and run the Address Parser Go REST service locally. Requires Golang and libpostal to be installed.

```bash
go mod tidy
go run main.go
```

--------------------------------

### Address Parsing Response Example

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

This is an example JSON response from the /parse endpoint, showing the parsed address components.

```json
{
  "house_number": "48",
  "road": "Leicester Square",
  "postcode": "Wc2h 7Lu",
  "city": "London",
  "country": "United Kingdom",
  "components": [
    {
      "label": "house_number",
      "value": "48"
    },
    {
      "label": "road",
      "value": "Leicester Square"
    },
    {
      "label": "city",
      "value": "London"
    },
    {
      "label": "postcode",
      "value": "Wc2h 7Lu"
    },
    {
      "label": "country",
      "value": "United Kingdom"
    }
  ]
}
```

--------------------------------

### Regenerate Swagger Documentation

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

Command to regenerate the Swagger documentation for the Address Parser Go REST API. Requires swag to be installed.

```bash
go generate
```

--------------------------------

### Configure Service Port and Docs Path

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

Environment variables to customize the HTTP address and Swagger documentation path for the Address Parser Go REST service.

```bash
PARSER_HTTP_ADDR=:8080
DOCS_PATH=/docs
```

--------------------------------

### NewLibPostalParser

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/libpostal

Initializes a new instance of the libPostalParser. It requires a logger for its operations.

```APIDOC
## func NewLibPostalParser

### Description
Initializes and returns a pointer to a new libPostalParser instance. This function requires a logger object to be passed as an argument.

### Signature
```go
func NewLibPostalParser(log logging.Logger) *libPostalParser
```

### Parameters
* **log** (logging.Logger) - A logger instance to be used by the parser.
```

--------------------------------

### Initialize Swagger Specification

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/docs

Defines the Swagger specification for the Address Parser API. This variable holds configuration details like version, host, base path, and API title/description.

```go
var SwaggerInfo = &swag.Spec{
	Version:          "1.0.0",
	Host:             "localhost:8080",
	BasePath:         "/",
	Schemes:          []string{},
	Title:            "Address Parser API",
	Description:      "This is the API for the address parser service",
	InfoInstanceName: "swagger",
	SwaggerTemplate:  docTemplate,
}
```

--------------------------------

### Create New AddressParserHandler

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Creates a new instance of AddressParserHandler. Requires a logger and an address parser implementation.

```go
func NewAddressParserHandler(log logging.Logger, parser addressparser.AddressParser) AddressParserHandler
```

--------------------------------

### Send a Sample Address Parsing Request

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

This `curl` command demonstrates how to send a POST request to the /parse endpoint to parse an address. It includes setting the content type and providing a JSON payload with the address and a title_case flag.

```bash
curl -X 'POST' \
  'http://localhost:8080/parse' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "48 Leicester Square, London WC2H 7LU, United Kingdom",
   "title_case": true
}'
```

--------------------------------

### NewLibPostalParser Function Signature

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/libpostal

This is the function signature for creating a new libpostal parser instance. It requires a logger as an argument.

```go
func NewLibPostalParser(log logging.Logger) *libpostalParser
```

--------------------------------

### NewAddressParserHandler

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Creates a new instance of the AddressParserHandler.

```APIDOC
## NewAddressParserHandler

### Description
Creates a new AddressParserHandler.

### Signature
```go
func NewAddressParserHandler(log logging.Logger, parser addressparser.AddressParser) AddressParserHandler
```
```

--------------------------------

### AddressParserInput Struct Definition

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the input structure for the address parser, including the address string, optional language and country, and a flag for title casing the output.

```go
type AddressParserInput struct {
	// the address to parse
	Address string `json:"address" validate:"required"`
	// the language of the address. Leave empty if you don't know
	Language string `json:"language,omitempty"`
	// the country of the address. Leave empty if you don't know
	Country string `json:"country,omitempty"`
	// if true then the responses will be title Cased. Default behavior of libpostal is not to do that.
	TitleCase bool `json:"title_case,omitempty"`
}
```

--------------------------------

### AddressParserHandler.Parse

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Handles the parsing of an address into its components.

```APIDOC
## POST /parse

### Description
Parse an address into its components. Parses an address into its components.

### Method
POST

### Endpoint
/parse

### Parameters
#### Request Body
- **input** (addressparser.AddressParserInput) - Required - AddressParserInput

### Response
#### Success Response (200)
- **object** (addressparser.Address) - Description

#### Error Response
- **400** {object} web.ErrResponse
- **422** {object} web.ErrResponse
- **500** {object} web.ErrResponse
```

--------------------------------

### Address Struct

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Represents a structured address after parsing.

```APIDOC
## Address Struct

### Description
This struct represents a parsed address, breaking it down into various components.

### Fields
- **House** (string) - Venue name or building name.
- **Category** (string) - Category for queries (e.g., "restaurants").
- **Near** (string) - Phrases like "in", "near" used after a category.
- **HouseNumber** (string) - The external building number.
- **Road** (string) - Street name(s).
- **Unit** (string) - Apartment, unit, office, or lot designator.
- **Level** (string) - Floor number indicator (e.g., "3rd Floor").
- **Staircase** (string) - Numbered or lettered staircase.
- **Entrance** (string) - Numbered or lettered entrance.
- **PoBox** (string) - Post office box number.
- **Postcode** (string) - Postal codes for mail sorting.
- **Suburb** (string) - Unofficial neighborhood name (e.g., "Harlem").
- **CityDistrict** (string) - Boroughs or districts within a city (e.g., "Brooklyn").
- **City** (string) - Human settlement (e.g., "New York").
- **Island** (string) - Named islands (e.g., "Maui").
- **StateDistrict** (string) - Second-level administrative division or county.
- **State** (string) - First-level administrative division (e.g., "California").
- **CountryRegion** (string) - Informal subdivision of a country.
- **Country** (string) - Sovereign nations and dependent territories.
- **WorldRegion** (string) - Used for appending regions like "West Indies".
- **Components** ([]AddressComponent) - The raw response components from libpostal.
```

--------------------------------

### Register AddressParserHandler Routers

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Registers the HTTP routes for the AddressParserHandler with a given web router.

```go
func (o *AddressParserHandler) RegisterRouters(r web.Router)
```

--------------------------------

### Parse Address Handler

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Handles HTTP requests to parse an address. It accepts JSON input and produces JSON output for the parsed address or error responses.

```go
func (o *AddressParserHandler) Parse(w http.ResponseWriter, r *http.Request)
```

--------------------------------

### AddressComponent Struct

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Represents a single component of a parsed address.

```APIDOC
## AddressComponent Struct

### Description
This struct represents a single labeled component of an address as defined by libpostal.

### Fields
- **Label** (string) - The label of the component (e.g., "road", "city").
- **Value** (string) - The value of the component (e.g., "Main Street", "New York").
```

--------------------------------

### AddressComponent Struct Definition

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the structure for an individual address component, containing a label and its corresponding value as provided by libpostal.

```go
type AddressComponent struct {
	// Label is the label of the component as defined by libpostal
	Label string `json:"label"`
	// Value is the value of the component as defined by libpostal
	Value string `json:"value"`
}
```

--------------------------------

### Address Struct Definition

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the structure for a parsed address, including various components like house, road, city, and state. It also includes raw components from libpostal.

```go
type Address struct {
	// venue name e.g. "Brooklyn Academy of Music", and building names e.g. "Empire State Building"
	House string `json:"house,omitempty"`
	// for category queries like "restaurants", etc.
	Category string `json:"category,omitempty"`
	// phrases like "in", "near", etc. used after a category phrase to help with parsing queries like "restaurants in Brooklyn"
	Near string `json:"near,omitempty"`
	// usually refers to the external (street-facing) building number. In some countries this may be a compount, hyphenated number which also includes an apartment number, or a block number (a la Japan), but libpostal will just call it the house_number for simplicity.
	HouseNumber string `json:"house_number,omitempty"`
	// street name(s)
	Road string `json:"road,omitempty"`
	// an apartment, unit, office, lot, or other secondary unit designator
	Unit string `json:"unit,omitempty"`
	// expressions indicating a floor number e.g. "3rd Floor", "Ground Floor", etc.
	Level string `json:"level,omitempty"`
	// numbered/lettered staircase
	Staircase string `json:"staircase,omitempty"`
	// numbered/lettered entrance
	Entrance string `json:"entrance,omitempty"`
	// post office box: typically found in non-physical (mail-only) addresses
	PoBox string `json:"po_box,omitempty"`
	// postal codes used for mail sorting
	Postcode string `json:"postcode,omitempty"`
	// usually an unofficial neighborhood name like "Harlem", "South Bronx", or "Crown Heights"
	Suburb string `json:"suburb,omitempty"`
	//  these are usually boroughs or districts within a city that serve some official purpose e.g. "Brooklyn" or "Hackney" or "Bratislava IV"
	CityDistrict string `json:"city_district,omitempty"`
	// any human settlement including cities, towns, villages, hamlets, localities, etc.
	City string `json:"city,omitempty"`
	// named islands e.g. "Maui"
	Island string `json:"island,omitempty"`
	// usually a second-level administrative division or county.
	StateDistrict string `json:"state_district,omitempty"`
	// a first-level administrative division. Scotland, Northern Ireland, Wales, and England in the UK are mapped to "state" as well (convention used in OSM, GeoPlanet, etc.)
	State string `json:"state,omitempty"`
	// informal subdivision of a country without any political status
	CountryRegion string `json:"country_region,omitempty"`
	// sovereign nations and their dependent territories, anything with an ISO-3166 code.
	Country string `json:"country,omitempty"`
	// currently only used for appending “West Indies” after the country name, a pattern frequently used in the English-speaking Caribbean e.g. “Jamaica, West Indies”
	WorldRegion string `json:"world_region,omitempty"`
	// Components is the raw response from libpostal
	Components []AddressComponent `json:"components"`
}
```

--------------------------------

### AddressParserInput Struct

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the input structure for the address parsing function.

```APIDOC
## AddressParserInput Struct

### Description
This struct holds the necessary information to perform an address parse operation.

### Fields
- **Address** (string) - Required - The address string to be parsed.
- **Language** (string) - Optional - The language of the address. Leave empty if unknown.
- **Country** (string) - Optional - The country of the address. Leave empty if unknown.
- **TitleCase** (bool) - Optional - If true, the response will be title-cased. Defaults to libpostal's behavior.
```

--------------------------------

### Parse Address

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest

This endpoint parses a given address string into its constituent components. It accepts an address and an optional boolean to title case the output.

```APIDOC
## POST /parse

### Description
Parses an address string into its components.

### Method
POST

### Endpoint
/parse

### Request Body
- **address** (string) - Required - The address string to parse.
- **title_case** (boolean) - Optional - If true, the output components will be title-cased.

### Request Example
```json
{
  "address": "48 Leicester Square, London WC2H 7LU, United Kingdom",
  "title_case": true
}
```

### Response
#### Success Response (200)
- **house_number** (string) - The parsed house number.
- **road** (string) - The parsed road name.
- **postcode** (string) - The parsed postcode.
- **city** (string) - The parsed city.
- **country** (string) - The parsed country.
- **components** (array) - An array of objects, each containing a 'label' and 'value' for a parsed component.

#### Response Example
```json
{
  "house_number": "48",
  "road": "Leicester Square",
  "postcode": "Wc2h 7Lu",
  "city": "London",
  "country": "United Kingdom",
  "components": [
    {
      "label": "house_number",
      "value": "48"
    },
    {
      "label": "road",
      "value": "Leicester Square"
    },
    {
      "label": "city",
      "value": "London"
    },
    {
      "label": "postcode",
      "value": "Wc2h 7Lu"
    },
    {
      "label": "country",
      "value": "United Kingdom"
    }
  ]
}
```
```

--------------------------------

### AddressParser Interface Definition

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the interface for an address parser, specifying a single method 'Parse' that takes an AddressParserInput and returns an Address and an error.

```go
type AddressParser interface {
	Parse(input AddressParserInput) (Address, error)
}
```

--------------------------------

### AddressParserHandler.RegisterRouters

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Registers the HTTP routes for the AddressParserHandler.

```APIDOC
## AddressParserHandler.RegisterRouters

### Description
Registers the routes for the AddressParserHandler.

### Signature
```go
func (o *AddressParserHandler) RegisterRouters(r web.Router)
```
```

--------------------------------

### AddressParser Interface

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

The AddressParser interface defines the contract for parsing address inputs.

```APIDOC
## AddressParser Interface

### Description
This interface defines the `Parse` method, which takes an `AddressParserInput` and returns a structured `Address` and an error.

### Methods
#### Parse
```go
Parse(input AddressParserInput) (Address, error)
```

- **input** (`AddressParserInput`): The input structure containing the address string and optional language/country information.
- **Returns** (`Address`, `error`): A structured `Address` object and an error if parsing fails.
```

--------------------------------

### Define Unparsable Address Error

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Defines the error returned when an address cannot be parsed. This is a global variable used for error checking.

```go
var ErrAddressUnparsable = errors.New("address is unparsable")
```

--------------------------------

### Define AddressParserHandler Type

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser/ports

Defines the AddressParserHandler struct used for handling address parsing requests.

```go
type AddressParserHandler struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### ErrAddressUnparsable Variable

Source: https://pkg.go.dev/github.com/gosom/address-parser-go-rest/addressparser

Error returned when an address cannot be parsed.

```APIDOC
## ErrAddressUnparsable Variable

### Description
This variable represents the error returned by the address parser when the input address is considered unparsable.

### Type
`error`
```
Tokens:
Raw