geolookup

geolookup

Basic webservice to look up location data based on an IP address or location query.

• Usage
• Configuration
• API
  • Formats
  • Responses
    • JSON
    • XML
    • HTML
    • Text
    • JSONP
      • Custom function name
  • Languages
• Building
• Licensing & thanks

Usage

Just run geolookup to start the service. The only requirements are that its data directory (default ./data) exist and that one of GEODB and GEODB_URL is set.

All options:

  -addr host:port
        host:port to bind to (default "127.0.0.1:4343")
  -conf file
        config file (optional)
  -conf.example format
        print an example config file in the specified format ("env" or "config") and exit
  -dir directory
        directory to store databases in (default "./data")
  -geodb path
        path to GeoLite2-City.mmdb file. If not set, you geolookup will try to fetch its own copy of the database from the URL specified by -geodb.url. You must provide one of -geodb or -geodb.url.
  -geodb.url URL
        URL of GeoLite2-City.mmdb to download. If set, geolookup will fetch its own copy of the GeoLite2 database from this URL. You must specify one of -geodb or -geodb.url.
  -health
        mount ping and expvar endpoints
  -verbose
        log debugging messages
  -version
        print version information and exit

Configuration

It can be configured by command-line options, a configuration file or environment variables. All settings are optional except -geodb/GEODB and -geodb.url/GEODB_URL. One of these must be specified.

If you do not specify a path to a MaxMind GeoLite2-City.mmdb database file with -geodb, geolookup will download its own copy from the URL specified with -geodb.url.

It will periodically update and reload its own copy. If you specify your own database, it will reload the data if the database file changes.

Use geolookup -conf.example (config|env) to print an example configuration or env file respectively.

The following CLI flags and corresponding environment variables are available:

API

There is only one endpoint, with an optional IP address or query:

• /[.ext] — Return location data for the caller's IP
• /<query>[.ext] — Return location data for places matching query
• /<ip>[.ext] — Return location data for IP address

Formats ###

The API returns the first data format specified in the request's Accept header. If your agent doesn't specify a preferred format, or it isn't one the API supports, JSON is returned. You can force a specific format by appending a file extension to the URL:

Responses

Note: A response may contain an empty list of results. This is not considered an error condition.

Responses contain the search query (or caller's IP address if no search query was specified) and either a list of zero or more locations if the lookup succeeded, or an error message if the lookup failed.

JSON

Response is an object that has a query field containing the search query or the IP address of the caller if no query was specified, and either a locations or an error field.

URL: /essen

{
    "query": "essen",
    "locations": [
        {
            "town":"Essen",
            "region":"North Rhine-Westphalia",
            "country":"Germany",
            "postcode":"45355",
            "timezone":"Europe/Berlin",
            "latitude":51.4698,"longitude":6.9517
        }
    ]
}

Or:

{"query": "essen", "error": "error message"}

XML

The root node is <response>. This will either contain a single <query> child plus either an <error> child or zero or more <location> children.

URL: /essen.xml

<response>
    <query>essen</query>
    <location>
        <town>Essen</town>
        <region>North Rhine-Westphalia</region>
        <country>Germany</country>
        <postcode>45355</postcode>
        <timezone>Europe/Berlin</timezone>
        <latitude>51.4698</latitude>
        <longitude>6.9517</longitude>
        </location>
<response>

Or:

<response>
    <query>essen</essen>
    <error>something went wrong</error>
</response>

HTML

Returns an HTML page containing either a table of locations or an error message.

Text

The first line of the response contains either the search query or the error message in the form query: <query> or error: <message>. All subsequent lines contain pipe-delimited fields.

The second line contains the column/field titles, and lines 3+ contain the search results.

URL: /essen.txt

query: essen
town|region|country|postcode|timezone|latitude|longitude
Essen|North Rhine-Westphalia|Germany|45355|Europe/Berlin|51.469800|6.951700

If a query fails, only an error message prefixed with error: is returned:

error: something went wrong

JSONP

Returns a script containing the function call locationData(query, locations, [errMsg]). query is the search query or the IP address of the caller if no search query was specified; locations is a list that corresponds to the locations field returned by the JSON version. errMsg is a string.

If the call succeeds, errMsg is not passed. If it fails, locations is null.

You can change the name of the function by adding ?fname=myFuncName to the URL.

URL: /essen.js

locationData("essen", [{
    "town":"Essen",
    "region":"North Rhine-Westphalia",
    "country":"Germany",
    "postcode":"45355",
    "timezone":"Europe/Berlin",
    "latitude":51.4698,
    "longitude":6.9517
}]);

Or:

locationData("essen", null, 'something went wrong');

URL: /essen.js?fname=myCallback

myCallback("essen", [{
    "town":"Essen",
    "region":"North Rhine-Westphalia",
    "country":"Germany",
    "postcode":"45355",
    "timezone":"Europe/Berlin",
    "latitude":51.4698,
    "longitude":6.9517
}]);

Or:

myCallback("essen", null, 'something went wrong');

Languages

The search API understands English, German, French and Spanish location names.

Building

Build using mage by running mage build in the project root directory (or mage dev for the development build).

As geolookup uses SQLite, gcc and sqlite3 are required.

All mage commands:

build       build production geolookup executable in working directory
clean       delete derived files
dev         build dev geolookup executable in working directory
generate    embed static assets in .go files
install     install geolookup
test        run unit tests
tidy        run go mod tidy

Licensing & thanks

geolookup is released under the MIT licence, and uses the following:

• GeoLite2 database by MaxMind
• go-chi/chi router
• peterbourgon/ff CLI/configuration library
• oschwald/geoip2-golang MaxMind database reader library
• sqlite for the location search
• mattn/go-sqlite3 to use SQLite3 from Go