@pretto/places

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

The library is typed but you can retrieve the types in the dist/types folder if needed

FAQ

How to implement the library?

yarn add @pretto/places

For municipality and zipcode

import { searchPlaces } from '@pretto/places';
import { MunicipalitySearchResult } from '@pretto/places/dist/types';

const result = await searchPlaces("paris", { limit: 21 })

// result object format :
[
    {
        label: "Paris 1er Arrondissement 75001",
        value: {
            center: [2.3359, 48.862],
            city: "Paris 1er Arrondissement",
            country: "fr",
            outline: [[{"latitude": 48.870688, "longitude": 2.347918},...]],
            zipcode: "75001",
        },
    },
    {
        label: "Paris 2e Arrondissement 75002",
        value: {
            center: [2.3411, 48.8677],
            city: "Paris 2e Arrondissement",
            country: "fr",
            outline: [Array],
            zipcode: "75002",
        },
    },
    ...
]

For department only

import { searchDepartment } from '@pretto/places'
import { DepartmentSearchResult } from '@pretto/places/dist/types';

const result = await searchDepartment("pa", { limit: 21 })

// result object format :
[
    {
        label: "Paris (75)",
        value: {
            code: "75",
            codeRegion: "11",
            country: "fr",
            region: {
                code: "11",
                nom: "Île-de-France"
            }
        },
    },
    {
        label: "Pas-de-Calais (62)",
        value: {
            code: "62",
            codeRegion: "32",
            country: "fr",
            region: {
                code: "32",
                nom: "Hauts-de-France"
            }
        },
    },
    ...
]

For Address (France only)

import { addressSearch } from '@pretto/places'
import { AddressSearchResult } from '@pretto/places/dist/types';

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

// result object format :
[
  {
    label: "42 Rue de Paradis 75010, Paris",
    value: {
      city: "Paris",
      country: "fr",
      street: "42 Rue de Paradis",
      zipcode: "75010",
    },
  },
  {
    label: "42 Rue de Paradis 95100, Argenteuil",
    value: {
      city: "Argenteuil",
      country: "fr",
      street: "42 Rue de Paradis",
      zipcode: "95100",
    },
  },
    ...
]

For country

import { searchCountry } from '@pretto/places'

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

For reverse geolocalisation

import { searchByCoordinates } from '@pretto/places'
import { MunicipalitySearchResult } from '@pretto/places/dist/types';

const results = await searchByCoordinates({ latitude: 48.87571729159758, longitude: 2.3503000982950883 })

// result object format :
[
  {
    label: "Paris 10e Arrondissement 75010",
    value: {
      center: [Object],
      city: "Paris 10e Arrondissement",
      country: "fr",
      outline: [Array],
      zipcode: "75010",
    },
  },
];

Options

You can pass options to the search function.

| Option | Type | Default Value | | ------------ | ----------- | --------------- | | debouncetime | number | 300 | | limit | number | 10 | | signal | AbortSignal | AbortController |

const debounceValue = 1000 // --- 1000 = 1s
const results = await searchPlaces('paris', { debouncetime: debounceValue, limit: 100 })

The signal allows you to abort a request if you no longer want to wait for the response. If it's not defined in the options, the library will use a locally managed AbortController(). If you need to manage your own abort, you can do it like this:

let controller = null
...
if(!search) {
   controller.abort()
   setResults([])
   return
}

if(controller) {
  controller.abort()
}

controller = new AbortController()
const places = await searchPlaces(search, {signal: controller.signal})

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://geo.api.gouv.fr/