@pretto/places

Allows you to search for an address, a postcode or a French department. You can also search a country.

FAQ

How to implement the library?

yarn add @pretto/places

For municipality and zipcode

import { municipalitySearch } from '@pretto/places'

const result = await municipalitySearch.get("paris", { limit: 21 })

// expected result : Paris (75001), Paris (75002), Paris (75003), ..., Paris (75020)
// result object format :
[
    {
        "label": "Paris (75001)",
        "value": {
            "city": "Paris",
            "country": "fr",
            "zipcode": "75001"
        }
    },
    {
        "label": "Paris (75002)",
        "value": {
            "city": "Paris",
            "country": "fr",
            "zipcode": "75002"
        }
    },
    ...
]

For department only

import { municipalitySearch } from '@pretto/places'

const result = await municipalitySearch.get("paris", { departmentOnly: true, limit: 21 })

// expected result : Paris (75), Parisot(81), Parisot (82), Cormeilles-en-Parisis (95), ...
// result object format :
[
    {
        "label": "Paris (75)",
        "value": {
            "city": "Paris",
            "country": "fr",
            "zipcode": "75"
        }
    },
    {
        "label": "Parisot (81)",
        "value": {
            "city": "Parisot",
            "country": "fr",
            "zipcode": "81"
        }
    },
    ...
]

For Address (France only)

import { addressSearch } from '@pretto/places'

const result = await addressSearch.get("55 rue de paradis", { limit: 10 })

// expected result : 55 Rue de Paradis 75010 Paris (75010), 55 Rue de Paradis 51160 Hautvillers (51160)...
// result object format :
[
    {
        "label": "55 Rue de Paradis 75010 Paris (75010)",
        "value": {
            "city": "Paris",
            "country": "fr",
            "street": "55 Rue de Paradis",
            "zipcode": "75010"
        }
    },
    {
        "label": "55 Rue de Paradis 51160 Hautvillers (51160)",
        "value": {
            "city": "Hautvillers",
            "country": "fr",
            "street": "55 Rue de Paradis",
            "zipcode": "51160"
        }
    },
    ...
]

For country

import { countrySearch } from '@pretto/places'

const countriesApi = countrySearch.init(ALGOLIA_COUNTRIES_APP_ID, ALGOLIA_COUNTRIES_API_KEY)
const results = await countriesApi.get('al', { limit: 10 })[
  // expected result : Allemagne (99109), Albanie (99125), Algerie (99352)
  // result object format :
  ({
    label: 'Allemagne (99109)',
    value: 'de',
  },
  {
    label: 'Albanie (99125)',
    value: 'al',
  },
  {
    label: 'Algerie (99352)',
    value: 'dz',
  })
]

For geolocalisation

import { geolocSearch } from '@pretto/places'

const results = await geolocSearch.get('75010')
// result object format :
// [{
//      city: 'Paris'
//      code: '75010',
//      coordinates: [2.347, 48.8589],
// }]

For reverse geolocalisation

import { reverseGeolocSearch } from '@pretto/places'

const results = await reverseGeolocSearch.get({ latitude: 48.8932244326416, longitude: 2.289395548568507 })
// result object format :
// [{
//      center: {latitude: 48.8946, longitude: 2.2874}
//      city: 'Levallois-Perret'
//      code: '92044',
//      coordinates: [2.2874, 48.8946],
//      zipcode: 92300,
// }]

Debounce

addressSearch, municipalitySearch and geolocSearch have defaut debounce value fixed to 300ms
You can override this value by passing debounce value as last argument

const debounceValue = 1000 // --- 1000 = 1s
const results = await countriesApi.get('al', { limit: 10 }, debounceValue)

How to publish a new version?

When a branch is merged into master, it will automatically deploy a new version to npm.

How it works?

This library is based on the API of data.gouv. These data are quite precise and are regularly updated:

• https://adresse.data.gouv.fr/
• https://api.gouv.fr/