<commit_before>Geocoding
=========

The `Geocoder` class from the `mapbox.services.geocoding` module provides
access to the Mapbox Geocoding API. You can also import it directly from the
`mapbox` module.

```python

>>> from mapbox import Geocoder

```

See https://www.mapbox.com/developers/api/geocoding/ for general documentation
of the API.

# Access Tokens

Geocoding requires an access token. Your Mapbox access token can be exported
into your environment

```bash

export MAPBOX_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

```

and it will be found by the `Geocoder` class when creating a new instance.

```python

>>> geocoder = Geocoder()
>>> import os
>>> geocoder.session.params['access_token'] == os.environ['MAPBOX_ACCESS_TOKEN']
True

```

Or it can be passed explicitly to the `Geocoder` constructor.

```python


>>> YOUR_ACCESS_TOKEN = os.environ['MAPBOX_ACCESS_TOKEN']
>>> geocoder = Geocoder(access_token=YOUR_ACCESS_TOKEN)

```

## Geocoding sources

If your account enables access to the *mapbox.places-permanent* dataset, you
can use it specify it with a keyword argument to the `Geocoder` constructor.

```python

>>> perm_geocoder = Geocoder(name='mapbox.places-permanent')

```

Best practice for access tokens and geocoding sources is to create a new
instance for each new access token or source dataset.

## Geocoder methods

The methods of the `Geocoder` class that provide access to the Geocoding API
return an instance of
[`requests.Response`](http://docs.python-requests.org/en/latest/api/#requests.Response).
In addition to the `json()` method that returns Python data parsed from the
API, the `Geocoder` responses provide a `geojson()` method that converts that
data to a GeoJSON like form.

## Limits

The Geocoding API is rate limited. Details of the limits and current state
are accessible through response headers.

```python

>>> response = geocoder.forward('Chester, NJ')
>>> response.headers['x-rate-limit-interval']
'60'
>>> response.headers['x-rate-limit-limit']
'600'
>>> response.headers['x-rate-limit-remaining'] # doctest: +SKIP
'599'
>>> response.headers['x-rate-limit-reset'] # doctest: +SKIP
'1447701074'

```

## Response format

The JSON response extends GeoJSON's `FeatureCollection`.

```python

>>> response = geocoder.forward('Chester, NJ')
>>> collection = response.json()
>>> collection['type'] == 'FeatureCollection'
True
>>> sorted(collection.keys())
['attribution', 'features', 'query', 'type']
>>> collection['query']
['chester', 'nj']

```

Zero or more objects that extend GeoJSON's `Feature` are contained in the
collection, sorted by relevance to the query.

```python

>>> first = collection['features'][0]
>>> first['type'] == 'Feature'
True
>>> sorted(first.keys())
['bbox', 'center', 'context', 'geometry', 'id', 'place_name', 'properties', 'relevance', 'text', 'type']

```

## Forward geocoding

Places at an address may be found using `Geocoder.forward()`.

```python

>>> response = geocoder.forward("200 queen street")
>>> response.status_code
200
>>> response.geojson()['features'][0]['place_name']
'200 Queen St W, Toronto, M5T 1T9, Canada'

```

## Forward geocoding with proximity

Place results may be biased toward a given longitude and latitude.

```python

>>> response = geocoder.forward(
...     "200 queen street", lon=-66.1, lat=45.3)
>>> response.status_code
200
>>> response.geojson()['features'][0]['place_name']
'200 Queen St, Saint John, E2L 2X1, Canada'

```

## Reverse geocoding

Places at a longitude, latitude point may be found using `Geocoder.reverse()`.

```python

>>> response = geocoder.reverse(lon=-73.989, lat=40.733)
>>> response.status_code
200
>>> for f in response.geojson()['features']:
...     print('{place_name}: {id}'.format(**f))
Atlas Installation, 124 E 13th St, New York, New York 10003, United States: poi.2701346205
Gramercy-Flatiron, New York, 10003, New York, United States: neighborhood.21161
New York, New York, United States: place.37501
10003, New York, United States: postcode.2254639497
New York, United States: region.628083222
United States: country.4150104525

```
<commit_msg>adjust geocoding results, see #84 for long term solution<commit_after>Geocoding
=========

The `Geocoder` class from the `mapbox.services.geocoding` module provides
access to the Mapbox Geocoding API. You can also import it directly from the
`mapbox` module.

```python

>>> from mapbox import Geocoder

```

See https://www.mapbox.com/developers/api/geocoding/ for general documentation
of the API.

# Access Tokens

Geocoding requires an access token. Your Mapbox access token can be exported
into your environment

```bash

export MAPBOX_ACCESS_TOKEN="YOUR_ACCESS_TOKEN"

```

and it will be found by the `Geocoder` class when creating a new instance.

```python

>>> geocoder = Geocoder()
>>> import os
>>> geocoder.session.params['access_token'] == os.environ['MAPBOX_ACCESS_TOKEN']
True

```

Or it can be passed explicitly to the `Geocoder` constructor.

```python


>>> YOUR_ACCESS_TOKEN = os.environ['MAPBOX_ACCESS_TOKEN']
>>> geocoder = Geocoder(access_token=YOUR_ACCESS_TOKEN)

```

## Geocoding sources

If your account enables access to the *mapbox.places-permanent* dataset, you
can use it specify it with a keyword argument to the `Geocoder` constructor.

```python

>>> perm_geocoder = Geocoder(name='mapbox.places-permanent')

```

Best practice for access tokens and geocoding sources is to create a new
instance for each new access token or source dataset.

## Geocoder methods

The methods of the `Geocoder` class that provide access to the Geocoding API
return an instance of
[`requests.Response`](http://docs.python-requests.org/en/latest/api/#requests.Response).
In addition to the `json()` method that returns Python data parsed from the
API, the `Geocoder` responses provide a `geojson()` method that converts that
data to a GeoJSON like form.

## Limits

The Geocoding API is rate limited. Details of the limits and current state
are accessible through response headers.

```python

>>> response = geocoder.forward('Chester, NJ')
>>> response.headers['x-rate-limit-interval']
'60'
>>> response.headers['x-rate-limit-limit']
'600'
>>> response.headers['x-rate-limit-remaining'] # doctest: +SKIP
'599'
>>> response.headers['x-rate-limit-reset'] # doctest: +SKIP
'1447701074'

```

## Response format

The JSON response extends GeoJSON's `FeatureCollection`.

```python

>>> response = geocoder.forward('Chester, NJ')
>>> collection = response.json()
>>> collection['type'] == 'FeatureCollection'
True
>>> sorted(collection.keys())
['attribution', 'features', 'query', 'type']
>>> collection['query']
['chester', 'nj']

```

Zero or more objects that extend GeoJSON's `Feature` are contained in the
collection, sorted by relevance to the query.

```python

>>> first = collection['features'][0]
>>> first['type'] == 'Feature'
True
>>> sorted(first.keys())
['bbox', 'center', 'context', 'geometry', 'id', 'place_name', 'properties', 'relevance', 'text', 'type']

```

## Forward geocoding

Places at an address may be found using `Geocoder.forward()`.

```python

>>> response = geocoder.forward("200 queen street")
>>> response.status_code
200
>>> response.geojson()['features'][0]['place_name']
'200 Queen St W, Toronto, M5T 1T9, Canada'

```

## Forward geocoding with proximity

Place results may be biased toward a given longitude and latitude.

```python

>>> response = geocoder.forward(
...     "200 queen street", lon=-66.1, lat=45.3)
>>> response.status_code
200
>>> response.geojson()['features'][0]['place_name']
'200 Queen St, Saint John, E2L 2X1, Canada'

```

## Reverse geocoding

Places at a longitude, latitude point may be found using `Geocoder.reverse()`.

```python

>>> response = geocoder.reverse(lon=-73.989, lat=40.733)
>>> response.status_code
200
>>> for f in response.geojson()['features']:
...     print('{place_name}: {id}'.format(**f))
Atlas Installation, 124 E 13th St, New York, New York 10003, United States: poi.2701346205
Gramercy-Flatiron, New York, 10003, New York, United States: neighborhood.21161
New York, New York, United States: place.34530
10003, New York, United States: postcode.2254639497
New York, United States: region.628083222
United States: country.4150104525

```

{'fraction_non_alphanumeric': 0.14252761927886368, 'fraction_numerical': 0.03253611751851402, 'mean_word_length': 5.293353705118411, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 177, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4846777', 'n_tokens_mistral': 2800, 'n_tokens_neox': 2546, 'n_words': 850}