geocoder-dadata/README.md

Dadata geocoder API client that supports caching and is written purely on typescript

# Why dadata?
* Amazing quality of Geocoding for territory of Russia
* Moderate pricing
* Lot's of other useful servicies like suggestions and others 



# Example
## Forward geocoding
```javascript
    const { Geocoder } = require('geocoder-dadata')
    const coder = new Geocoder({ api_token: 'YOUR DATATA API TOKEN', api_secret: 'YOUR DATATA API SECRET' })

    coder.geocode('Москва, Мичуринский пр-т, 9к1').then(resp => {

        if (resp.ok) {

            console.log('Geo coordinates:', resp.geo)
            console.log('Detailed response:', resp.results)
        }

        else {

            console.log('Request has failed')
            console.log('Check the full response from dadata:', resp)
            console.log('Or you can check response status only:', resp.status.code, resp.status.message)
        }
    })
```





# Make it safe

To make your code safer put your API token and secret into environment variables `DADATA_API_TOKEN` и `DADATA_API_SECRET` and avoid passing it to the geocoder constructor as plain text in your code:

```javascript
    const coder = new geocoder() //In this case your are expected to provide your API credebtials in DADATA_API_TOKEN и DADATA_API_SECRET variable before using geocoder constructor
```





# Response caching

By default the `geocoder` automaticaly caches responses *in memory*.
The cache is shared among all instances of the `geocoder` class that use *the same API KEY*.
If you change an API key, it makes cached responses effectively invisible to other `geocoder` instances if they use other API keys.

If you would like a particular `geocoder` instance not to use caching you may provide it a `{ cached: false }` option like so:

```javascript
    const coder = new geocoder({ cached: false })
    // By default "cached" option is set to true
```





# Batch request throttling
It's important to note that just like any other service provider dadata puts certain [limits](https://dadata.ru/api/clean/address/) on how much requests you may send per second (10 requests per second). When it comes to batch processing, a pace keeping techniques comes into play. The `geocoder-dadata` client supports requests throttling by default so you can rest peacefully. If you send lots of requests to `geocoder-dadata` they will be arranged in a queue and scheduled to be sent at rate of 5 request per second. If you want to tweek internal pace keeper by `pace_limit` option like so:
```javascript
    const coder = new geocoder({ pace_limit: 10 })
        // This will limit the geocoder to 10 requests per second.
        // Put here whatever suits your contract with dadata
        // By default "pace_limit" equals to 5
```