Skip to content

Interfaces and utilities around GeocodeJSON format & Geocode data provider

License

Notifications You must be signed in to change notification settings

p-j/geocodejson

Repository files navigation

GeocodeJSON

GeocodeJSON packages are a collection of small utility to work with geocoding API such as Google Geocoding API, HERE Geocoding API, Opencage, etc... As well as self hosted solution like Mimirsbrunn.

These packages provide a simple inteface for geocoding addresses exposing the underlying APIs filtering capabilities while returning all response in a standard format: GeocodeJSON, a GeoJSON extension.

These packages leverage cross-fetch to work on both backend & frontend

lerna lerna codecov Build Status FOSSA Status

GeocodeJSON packages

Package Version Changelog
@p-j/geocodejson-googleapis version changelog
@p-j/geocodejson-here Contribution welcome
@p-j/geocodejson-opencage version changelog
@p-j/geocodejson-ban version changelog
@p-j/geocodejson-mimirsbrunn Contribution welcome
@p-j/geocodejson-types version changelog

Usage

Each provider package export 2 main functions:

  • geocode: call the API with your input and options and get the raw response from the API
  • parse: parse the raw response from the API and return a properly formatted GeocodeJSON response equivalent

Refer to each packages README for a list of options linked to the underlying API capabilities.

Roadmap

⚠️ I'm not currently working on this package so this roadmap is more of a reminder of what would be good to add than a promise of any further development.

✨ Contribution are however more than welcome.

aka: TODO

  • Implement more providers (Here & Mimirsbrunn are top priorities)
  • Define a unified format for options for all suppoerted providers (eg: filtering, biasing, language etc...)
  • Add reverse geocoding
  • Add autocomplete
  • Add feature details endpoint (aka: place details)

Inspiration

This package was inspired by the geocodejson-spec, geocoder-geojson, geo-coder and node-geocoder

Why another geocoder then?

The list or prerequisite for this project was as follow:

  • Work as closely as possible with standard format (GeoJSON / GeocodeJSON) for interoperability and compatibility with other tools
  • Make it extensible, avoid packaging everything in one big package
  • Make it composable, expose raw output from geocoding API to allow manipulation, data extraction or caching, expose prepared query arguments to be used with any fetch/http library
  • Make it fully typed to help with coding & documentation
  • Make it isomorphic: usable in the browser, on the server or in environment like Cloudflare Workers

None of the projects I've found allowed for all those options, and none had an easy way of being built upon to propose the same added value, so here we are.

License

FOSSA Status