README

nominatim-browser

A browser-usable client for Open Street Map's Nominatim service. It can be used to lookup the latitude and longitude coordinates for an address and to lookup the address for a pair of latitude and longitude coordinates.

Goals

While there are plenty of Nominatim clients available on NPM, none of them are currently built for use in the browser. Instead, they rely on Node's http module, or other Node-only http frameworks. On top of that, none of those clients offer TypeScript definitions.

The goal of nominatim-browser is to fill both of those holes by providing a Nominatim client that can be used from the browser with TypeScript definitions.

Installing

You can install this package from NPM or with Yarn:

npm install nominatim-browser --save

# Or via Yarn
yarn add nominatim-browser

Usage

Import the lib:

// With ES6-style imports
import * as Nominatim from "nominatim-browser";

// With node-style requires:
var Nominatim = require("nominatim-browser";

If you can't use require or ES6-imports, this package also provides a webpacked version (dist/nominatim-browser.webpacked.js) which bundles all of the necessary dependencies. Once loaded, the bundled script will make all nominatim-browser functions available under the Nominatim variable.

<script type="text/javascript" src="dist/nominatim-browser.webpacked.js" ></script>
<script type="text/javascript">
//Nominatim is now available
console.log("Nominatim is", Nominatim);
</script>

Nominatim.geocode(request: GeocodeRequest): Promise<NominatimResponse[]>

Looks up the latitude and longitude data for a given address, returning an array of NominatimResponse objects found for the address.

(Please review the TypeScript definition file for full documentation on GeocodeRequest, NominatimResponse and all other object types.)

Nominatim.geocode({
    city: "Minneapolis",
    state: "MN",
    country: "US",
    addressdetails: true
})
.then((results: NominatimResponse[]) =>
{
    var result = results[0];
    
    console.log(result.lat);          // '44.9772995'
    console.log(result.lon);          // '-93.2654691'
    console.log(result.display_name); // 'Minneapolis, Hennepin County, Minnesota, United States of America'
    
    // result.address is only returned when 'addressdetails: true' is sent in the geocode request
    console.log(result.address.city);    // 'Minneapolis'
    console.log(result.address.county);  // 'Hennepin County'
    console.log(result.address.state);   // 'Minnesota'
    console.log(result.address.country); // 'United States of America'
    
})
.catch((error) =>
{
    console.error(error);
});

Nominatim.reverseGeocode(request: ReverseGeocodeRequest): Promise<NominatimResponse>

Looks up the address data for a pair of latitude and longitude coordinates.

Nominatim.reverseGeocode({
    lat: "44.9772995",
    lon: "-93.2654691",
    addressdetails: true
})
.then((result : NominatimResponse) =>
{
    console.log(result.display_name); // 'Minneapolis City Hall, South 4th Street, St Anthony West, Phillips, Minneapolis, Hennepin County, Minnesota, 55415, United States of America'
    
    // result.address is only returned when 'addressdetails: true' is sent in the request
    console.log(result.address.city);    // 'Minneapolis'
    console.log(result.address.county);  // 'Hennepin County'
    console.log(result.address.state);   // 'Minnesota'
    console.log(result.address.country); // 'United States of America'
})
.catch((error) =>
{
    console.error(error); 
});

Nominatim.lookupAddress(request: LookupRequest): Promise<NominatimResponse[]>

Looks up the address for multiple Open Street Maps objects like node, way or relation.

Nominatim.lookupAddress({
    osm_ids: "R136712,R146656" //A list of OSM ids separated by comma
})
.then((results: NominatimResponse[]) =>
{
    // First result will be the R136712 (Minneapolis) id. 
    var result = results[0];
    
    console.log(result.display_name);    // 'Minneapolis, Hennepin County, Minnesota, United States of America'
    console.log(result.address.city);    // 'Minneapolis'
    console.log(result.address.county);  // 'Hennepin County'
    console.log(result.address.state);   // 'Minnesota'
    console.log(result.address.country); // 'United States of America'
})
.catch((error) =>
{
    console.error(error); 
});

Types

Please review the TypeScript definition file for full documentation on GeocodeRequest, NominatimResponse and all other object types.

Contributing to nominatim-browser

In order to build nominatim-browser, ensure that you have git, Node.js, NPM and gulp-cli installed.

Clone a copy of the master nominatim-browser git repo:

git clone https://github.com/nozzlegear/nominatim-browser.git

Change to the nominatim-browser directory:

cd nominatim-browser

Install the necessary NPM packages:

npm install

Run gulp to build the TypeScript lib and test files:

gulp

Run tests via NPM's test command:

npm run test

While I really appreciate any contribution, please make sure that they have test coverage, and that all tests are written in TypeScript with Mocha and Chai.

When you're ready to contribute, make a pull request!

nominatim-browser-custom

Usage no npm install needed!