Nighttime Pachinko Marathon
    Wondering what’s next for npm?Check out our public roadmap! »

    nominatim-browser
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    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!

    License

    MIT © Joshua Harms

    Install

    npm i nominatim-browser

    DownloadsWeekly Downloads

    557

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    294 kB

    Total Files

    29

    Last publish

    Collaborators

    • avatar