@p-j/geocodejson-ban

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

@p-j/geocodejson-ban

Geocode & format to GeocodeJSON using the French "Base Adresse Nationale" API

Usage

import { geocode, parse, getFetchArgs } from '@p-j/geocodejson-ban'

// if you want to use your own fetch wrapper / http library
const { url, options } = getFetchArgs({
  q: 'Place de la République, Paris, France',
  limit: 1,
  postcode: '75011',
})
// url = 'https://api-adresse.data.gouv.fr/search?limit=1&postcode=75011&q=Place+de+la+R%C3%A9publique,+Paris,+France'
// options = { method: 'GET' }

// using cross-fetch; also adds the "query" property to the response
const rawResponseFromBANApi = await geocode({
  address: 'Place de la République, Paris, France',
  limit: 1,
})
// {
//   type: 'FeatureCollection',
//   version: 'draft',
//   attribution: 'BAN',
//   licence: 'ETALAB-2.0',
//   query: 'Place de la République, Paris, France',
//   features: [
//     {
//       type: 'Feature',
//       geometry: {
//         type: 'Point',
//         coordinates: [2.365475, 48.867039],
//       },
//       properties: {
//         label: 'Place de la République 75011 Paris',
//         score: 0.9670254545454545,
//         id: '75111_8159',
//         name: 'Place de la République',
//         postcode: '75011',
//         citycode: '75111',
//         x: 653452.35,
//         y: 6863188.08,
//         city: 'Paris',
//         district: 'Paris 11e Arrondissement',
//         context: '75, Paris, Île-de-France',
//         type: 'street',
//         importance: 0.63728,
//       },
//     },
//   ],
//   limit: 1,
// }

const geocodeJSONFormatedResults = parse(rawResponseFromBANApi)
// {
//   type: 'FeatureCollection',
//   geocoding: {
//     version: 'draft',
//     attribution: 'BAN',
//     licence: 'ETALAB-2.0',
//     query: 'place de la république paris',
//   },
//   features: [
//     {
//       type: 'Feature',
//       geometry: {
//         type: 'Point',
//         coordinates: [2.365475, 48.867039],
//       },
//       properties: {
//         geocoding: {
//           label: 'Place de la République 75011 Paris',
//           score: 0.9670254545454545,
//           id: '75111_8159',
//           name: 'Place de la République',
//           postcode: '75011',
//           citycode: '75111',
//           x: 653452.35,
//           y: 6863188.08,
//           city: 'Paris',
//           district: 'Paris 11e Arrondissement',
//           context: '75, Paris, Île-de-France',
//           type: 'street',
//           importance: 0.63728,
//         },
//       },
//     },
//   ],
//   limit: 1,
// }