https://github.com/nozzlegear/nominatim-browser
A Nominatim client that can be used from the browser.
https://github.com/nozzlegear/nominatim-browser
Last synced: 6 months ago
JSON representation
A Nominatim client that can be used from the browser.
- Host: GitHub
- URL: https://github.com/nozzlegear/nominatim-browser
- Owner: nozzlegear
- License: mit
- Created: 2016-05-06T16:09:51.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-06T17:31:15.000Z (almost 3 years ago)
- Last Synced: 2025-03-27T20:12:11.076Z (7 months ago)
- Language: TypeScript
- Size: 492 KB
- Stars: 13
- Watchers: 2
- Forks: 7
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nominatim-browser
A browser-usable client for [Open Street Map's **Nominatim** service](http://wiki.openstreetmap.org/wiki/Nominatim). 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](https://npmjs.com/package/nominatim-browser) or with [Yarn](https://github.com/yarnpkg/yarn):
```bash
npm install nominatim-browser --save
# Or via Yarn
yarn add nominatim-browser
```
## Usage
Import the lib:
```js
// 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.
```html
//Nominatim is now available
console.log("Nominatim is", Nominatim);
```
### Nominatim.geocode(request: GeocodeRequest): Promise\
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](https://github.com/nozzlegear/nominatim-browser/blob/master/dist/nominatim-browser.d.ts) for full documentation on `GeocodeRequest`, `NominatimResponse` and all other object types.)
```ts
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\
Looks up the address data for a pair of latitude and longitude coordinates.
```ts
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\
Looks up the address for multiple Open Street Maps objects like node, way or relation.
```ts
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);
});
```
## Specifying a custom server URL
All three functions (`.geocode`, `.reverseGeocode` and `.lookupAddress`) take a second, optional parameter that lets you customize the Nominatim server URL:
```ts
const address = {
city: "Minneapolis",
state: "MN",
country: "US",
addressdetails: true
};
const customUrl = "https://example.com";
Nominatim.geocode(address, customUrl).then((results: NominatimResponse[]) =>
{
console.log(results);
})
.catch((error) =>
{
console.error(error);
});
```
## Types
Please [review the TypeScript definition file](https://github.com/nozzlegear/nominatim-browser/blob/master/dist/nominatim-browser.d.ts) 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](http://git-scm.com/downloads), [Node.js](https://nodejs.org), [NPM](https://npmjs.com) and [gulp-cli](https://npmjs.com/package/gulp-cli) installed.
Clone a copy of the master `nominatim-browser` git repo:
```bash
git clone https://github.com/nozzlegear/nominatim-browser.git
```
Change to the `nominatim-browser` directory:
```bash
cd nominatim-browser
```
Install the necessary NPM packages:
```bash
npm install
```
Run `gulp` to build the TypeScript lib and test files:
```bash
gulp
```
Run tests via NPM's `test` command:
```bash
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](http://mochajs.org/) and [Chai](http://chaijs.com/).
When you're ready to contribute, [make a pull request](https://github.com/nozzlegear/nominatim-browser/pull/new/master)!
## License
MIT © [Joshua Harms](https://nozzlegear.com)