Go 1.13+. Build steps for older go versions may vary.
go build .
ls ./libpostal-rest
This service can be configured with the following environment variables:
LISTEN_HOST - hostname or IP address to listen on - default: 0.0.0.0 (all interfaces)
LISTEN_PORT - port the server is listening on - default: 8080
LOG_LEVEL - setting the global log level - default info (more on that further below)
LOG_STRUCTURED - if set to true, the logger generates structured JSON log output, otherwise it will create "pretty" output - default: false
PROMETHEUS_ENABLED - set to true enables Prometheus metrics collector and endpoint, 'false' or missing disables it - default: false
PROMETHEUS_PORT - port number where Prometheus exposes the /metrics endpoint - default: 9090
Logging has been implemented using zerolog which is a super-fast structured logger outputting JSON. However, zerolog also allows outputting non-structured ("pretty printed") log lines, which is the default setting. zerolog also supports different log levels which are as follows:
panicfatalerrorwarninfodebugtrace
For example, to change the default log level from info to debug one would set the following environment variable:
export LOG_LEVEL='debug'
Please note, if the string set in the environment variable is not one of the valid ones listed above, the service will log a warning and used the default level
info.
The service has been instrumented with the Prometheus client library. By default metrics collection and the Prometheus endpoint is disabled. It can be enabled by setting the environment variable PROMETHEUS_ENABLED to true. Once enabled, the metrics can be scraped at the following endpoint:
http://<LISTEN_HOST>:<PROMETHEUS_PORT>/metrics
The metrics endpoint exposes the default golang metrics as well as the following custom metrics of the service:
libpostal_expand_reqs_total- The total number of processed expand requestslibpostal_expand_durations_historgram_ms- Latency distributions of expand calls in millisecondslibpostal_parse_reqs_total- The total number of processed parse requestslibpostal_parse_durations_historgram_ms- Latency distributions of parse calls in millisecondslibpostal_expandparse_reqs_total- The total number of processed expandparse requestslibpostal_expandparse_durations_historgram_ms- Latency distributions of expandparse calls in milliseconds
Replace <host> with your host, e.g. localhost
Request
curl -X POST -d '{"query": "100 main st buffalo ny"}' http://<host>:8080/parser
Response
[
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main st"
},
{
"label": "city",
"value": "buffalo"
},
{
"label": "state",
"value": "ny"
}
]
Request
curl -X POST -d '{"query": "100 main st buffalo ny"}' http://<host>:8080/expand
Response
[
"100 main saint buffalo new york",
"100 main saint buffalo ny",
"100 main street buffalo new york",
"100 main street buffalo ny"
]
Request
IMPORTANT NOTE: if the
langsarray contains an invalid language specifier, e.g."xyz", the string will not be expanded for that specified language input and instead the original query string will be returned.
curl -X POST -d "{\"query\": \"100 main st buffalo ny\", \"langs\": [\"de\"]}" http://<host>:8080/expand
Response
[
""100 main sankt buffalo ny""
]
Incorrect language specified
Request
curl -X POST -d "{\"query\": \"100 main st buffalo ny\", \"langs\": [\"de\", \"xyz\"]}" http://<host>:8080/expand
Response
[
"100 main sankt buffalo ny",
"100 main st buffalo ny"
]
Request
curl -X POST -d '{"query": "100 main st buffalo ny"}' http://<host>:8080/expandparser
Original query is parsed and added with "type": "query".
All query expansions are parsed and added with "type": "expansion"
Response
[
{
"data": "100 main st buffalo ny",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main st"
},
{
"label": "city",
"value": "buffalo"
},
{
"label": "state",
"value": "ny"
}
],
"type": "query"
},
{
"data": "100 main saint buffalo ny",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main"
},
{
"label": "city",
"value": "saint buffalo"
},
{
"label": "state",
"value": "ny"
}
],
"type": "expansion"
},
{
"data": "100 main saint buffalo new york",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main"
},
{
"label": "city",
"value": "saint buffalo"
},
{
"label": "state",
"value": "new york"
}
],
"type": "expansion"
},
{
"data": "100 main street buffalo ny",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main street"
},
{
"label": "city",
"value": "buffalo"
},
{
"label": "state",
"value": "ny"
}
],
"type": "expansion"
},
{
"data": "100 main street buffalo new york",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main street"
},
{
"label": "city",
"value": "buffalo"
},
{
"label": "state",
"value": "new york"
}
],
"type": "expansion"
}
]
Request
curl -X POST -d "{\"query\": \"100 main st buffalo ny\", \"langs\": [\"fr\"]}" http://<host>:8080/expandparser
Response
[
{
"data": "100 main st buffalo ny",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main st"
},
{
"label": "city",
"value": "buffalo"
},
{
"label": "state",
"value": "ny"
}
],
"type": "query"
},
{
"data": "100 main saint buffalo ny",
"parsed": [
{
"label": "house_number",
"value": "100"
},
{
"label": "road",
"value": "main"
},
{
"label": "city",
"value": "saint buffalo"
},
{
"label": "state",
"value": "ny"
}
],
"type": "expansion"
}
]