node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »



A Koa middleware to retrieve gelocation information for a request based on the request's originating IP address.

The middleware uses the Telize API to geolocate incoming requests, and stores the retrieved information in state.geo. For information about the data format and information available, refer to the "JSON Output Schema" available on the Telize home page.

If the API request is unsuccessful for any reason, the middleware will populate state.geo.error with an object of the following format:

        "statusCode": 400, //the HTTP status code of the failed request 
        "message": "Invalid IP" //the error message, if any, from Telize 


    var app = require('koa')();
    app.use(function *() {


You can pass an options hash as the sole argument to koa-geo-telize to configure the middleware. Available options include:

  • pathRegexWhitelist (default: undefined): By default, the middleware will run against all requests, but if this option is passed, it will only run for requests whose path matches a regex in the whitelist. Expects an Array of regexs.

  • serviceURL (default: The path to the Telize API that should be used for geolocation. The live API is not rate-limited, but there are no guarantees as to its availability, so you can self-host it if you'd prefer.