<commit_before># Whereabouts [![CircleCI](https://circleci.com/gh/HowNetWorks/whereabouts.svg?style=shield)](https://circleci.com/gh/HowNetWorks/whereabouts)

An HTTP service for mapping IPv4 and IPv6 addresses to countries and continents.
Written in Go (version 1.7.4).

Uses MaxMind's [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
licensed GeoLite2 City database (available from https://www.maxmind.com/) by
default. However the service can be configured to use any other similarly
formatted database.

The service, once launched, polls the database URL periodically and downloads
updated versions automatically. The service can also be seeded with an initial
database, e.g. for speeding up service startup from a Docker image.

## Quick Start

Launch Whereabouts as a Docker container:

```sh
$ docker run -ti --rm -p 8080:8080 hownetworks/whereabouts
```

Give the service a moment to download the database. Once that's done you
can start sending queries to localhost port 8080:

```sh
$ curl http://localhost:8080/ip/8.8.8.8
```

## Command-line Options

- `host` The IP address or hostname that the HTTP server should listen to. Default: `localhost`.
- `port` The port that the HTTP server should listen to. Default: `8080`.
- `update-interval` How often database updates should be checked from `hash-url`/`update-url`. Uses Go's [Duration format](https://golang.org/pkg/time/#ParseDuration). Default: 4 hours.
- `update-url` A URL for updating the database. Default: MaxMind's [GeoLite2 City](https://dev.maxmind.com/geoip/geoip2/geolite2/) database.
- `hash-url` A URL pointing to a file containing an MD5 sum of the data in `update-url`. Useful for checking whether the database has updated without actually downloading the whole database. Default: Off by default, except when `update-url` points to its default value.
- `init-url` A URL for the initial database load. Can be used to seed the service by e.g. baking in a snapshot of the database into the service's a Docker image. Default: The initial load will be performed from `update-url`.

All URL options allow `http`, `https` and `file` URLs.

## API

The service supports requests to `/ip/IP_ADDRESS` where `IP_ADDRESS`
can be an IPv4 or IPv6 address.

Let's assume the service is running on localhost port 8080 and has done the
initial database load. To query Google's DNS service addresses run the following:

```sh
$ curl http://localhost:8080/ip/8.8.8.8
{"continent":{"code":"NA","name":"North America"},"country":{"code":"US","name":"United States"},"city":"Mountain View"}
$ curl http://localhost:8080/ip/2001:fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b
{"continent":{"code":"NA","name":"North America"},"country":{"code":"US","name":"United States"}}
$ curl http://localhost:8080/ip/192.0.2.0
{}
```

If the queried IP isn't a valid IPv4/6 address the service returns status code
422 (Unprocessable Entity) with a JSON formatted message object:

```sh
$ curl http://localhost:8080/ip/not.an.ip.address
{"message": "Not an IPv4/IPv6 address"}
```

GET requests to the root path `/` return the status code 200, but only after the
initial database load has been done. This can be used for service readiness
checks.

## Baking the Database into an Image

The Docker image does not contain a copy of the MaxMind GeoLite2 City
database, which is always loaded from MaxMind's servers when Whereabouts
starts. For situations where this is not feasible (e.g. environments without
external network connectivity) you can build a custom image with that uses
baked-in data for the initial load.

Create a Dockerfile with `hownetworks/whereabouts` as the base image:

```dockerfile
# Instead of :latest use an explicit version such as :v0.3.4 in production<commit_msg>Update README.md to point to v0.4.0<commit_after># Whereabouts [![CircleCI](https://circleci.com/gh/HowNetWorks/whereabouts.svg?style=shield)](https://circleci.com/gh/HowNetWorks/whereabouts)

An HTTP service for mapping IPv4 and IPv6 addresses to countries and continents.
Written in Go (version 1.7.4).

Uses MaxMind's [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
licensed GeoLite2 City database (available from https://www.maxmind.com/) by
default. However the service can be configured to use any other similarly
formatted database.

The service, once launched, polls the database URL periodically and downloads
updated versions automatically. The service can also be seeded with an initial
database, e.g. for speeding up service startup from a Docker image.

## Quick Start

Launch Whereabouts as a Docker container:

```sh
$ docker run -ti --rm -p 8080:8080 hownetworks/whereabouts
```

Give the service a moment to download the database. Once that's done you
can start sending queries to localhost port 8080:

```sh
$ curl http://localhost:8080/ip/8.8.8.8
```

## Command-line Options

- `host` The IP address or hostname that the HTTP server should listen to. Default: `localhost`.
- `port` The port that the HTTP server should listen to. Default: `8080`.
- `update-interval` How often database updates should be checked from `hash-url`/`update-url`. Uses Go's [Duration format](https://golang.org/pkg/time/#ParseDuration). Default: 4 hours.
- `update-url` A URL for updating the database. Default: MaxMind's [GeoLite2 City](https://dev.maxmind.com/geoip/geoip2/geolite2/) database.
- `hash-url` A URL pointing to a file containing an MD5 sum of the data in `update-url`. Useful for checking whether the database has updated without actually downloading the whole database. Default: Off by default, except when `update-url` points to its default value.
- `init-url` A URL for the initial database load. Can be used to seed the service by e.g. baking in a snapshot of the database into the service's a Docker image. Default: The initial load will be performed from `update-url`.

All URL options allow `http`, `https` and `file` URLs.

## API

The service supports requests to `/ip/IP_ADDRESS` where `IP_ADDRESS`
can be an IPv4 or IPv6 address.

Let's assume the service is running on localhost port 8080 and has done the
initial database load. To query Google's DNS service addresses run the following:

```sh
$ curl http://localhost:8080/ip/8.8.8.8
{"continent":{"code":"NA","name":"North America"},"country":{"code":"US","name":"United States"},"city":"Mountain View"}
$ curl http://localhost:8080/ip/2001:fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b
{"continent":{"code":"NA","name":"North America"},"country":{"code":"US","name":"United States"}}
$ curl http://localhost:8080/ip/192.0.2.0
{}
```

If the queried IP isn't a valid IPv4/6 address the service returns status code
422 (Unprocessable Entity) with a JSON formatted message object:

```sh
$ curl http://localhost:8080/ip/not.an.ip.address
{"message": "Not an IPv4/IPv6 address"}
```

GET requests to the root path `/` return the status code 200, but only after the
initial database load has been done. This can be used for service readiness
checks.

## Baking the Database into an Image

The Docker image does not contain a copy of the MaxMind GeoLite2 City
database, which is always loaded from MaxMind's servers when Whereabouts
starts. For situations where this is not feasible (e.g. environments without
external network connectivity) you can build a custom image with that uses
baked-in data for the initial load.

Create a Dockerfile with `hownetworks/whereabouts` as the base image:

```dockerfile
# Instead of :latest use an explicit version such as :v0.4.0 in production
{'fraction_non_alphanumeric': 0.10698108180122569, 'fraction_numerical': 0.029176658673061552, 'mean_word_length': 4.708745247148289, 'pattern_counts': {'":': 28, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '274053', 'n_tokens_mistral': 2368, 'n_tokens_neox': 2117, 'n_words': 936}