Quickstart: Patterns and Best Practices¶
Initializing the API¶
To initialize the WalkScoreAPI
object all you
need to do is instantiate it:
from walkscore import WalkScoreAPI
# supplying an API key
walkscore = WalkScoreAPI(api_key = 'MY API KEY GOES HERE')
# using an API key in the "WALKSCORE_API_KEY" environment variables
walkscore = WalkScoreAPI()
Configuring the HTTP Client¶
You can heavily customize the HTTP client used by the WalkScore Library. By default, the library will look for HTTP libraries in the following order:
Tip
You can also override the HTTP client by subclassing the
HTTPClient
class.
There are three ways to customize / configure the HTTP client:
Subclass the
HTTPClient
class.Supply a proxy URL.
Configure the maximum number of retries.
Subclassing the Client¶
from walkscore import WalkScoreAPI
from my_custom_client import MyCustomHTTPClient
walkscore = WalkScoreAPI(http_client = MyCustomHTTPClient)
Configuring a Proxy¶
from walkscore import WalkScoreAPI
walkscore = WalkScoreAPI(proxy = 'http://www.some-proxy-url')
Configuring the Maximum Number of Retries¶
If the WalkScore Library is unable to get a response from the WalkScore API, it will automatically apply an exponential backoff/retry strategy. However, you can configure the maximum number of retries that it attempts. This can be configured in two ways:
By setting the
BACKOFF_DEFAULT_TRIES
environment variable.By passing the maximum number of retries in the
max_retries
argument:from walkscore import WalkScoreAPI walkscore = WalkScoreAPI(max_retries = 5)
Getting Scores¶
To retrieve scores, all you need to do is to call the
get_score()
method on the initialized API:
from walkscore import WalkScoreAPI
walkscore = WalkScoreAPI(api_key = 'MY API KEY GOES HERE')
result = walkscore.get_score(latitude = 123.45, longitude = 54.321)
Note
In order to retrieve a score from the API, you must supply the latitude and longitude of the point you are looking for. The WalkScore API does not support geocoding based on addresses, although an address can provide more precise results if you supply it as well.
Tip
In order to get better performance out of the underlying WalkScore API, you may
want to suppress the calculation / retrieval of
TransitScores and/or BikeScores if
you don’t need them. To do that, all you need to do is pass the appropriate
arguments into the get_score()
method:
result = walkscore.get_score(latitude = 123.45,
longitude = 54.321,
return_transit_score = False,
return_bike_score = False)
The results returned by the get_score()
method
are always LocationScore
instances.
Working with Scores¶
When the WalkScore Library has retrieved a score for a given set of coordinates,
you can work with it as any other Python object. See the LocationScore
reference documentation for more insight into its properties.
However, there are a number of key serialization / deserialization methods that you may find useful:
.to_json()
which returns a JSON representation of the location score, either normalized to a cleaner/more consistent structure preferred by the WalkScore Library or mirroring the WalkScore API’s JSON structure.from_json()
which returns aLocationScore
instance generated from a JSON string.to_dict()
which returns adict
representation fo the location score, either normalized to a cleaner/more consistent structure preferred by the WalkScore Library or mirroring the WalkScore API’s JSON structure.from_dict()
which returns aLocationScore
instance generated from adict