Quickstart: Patterns and Best Practices¶

Installation
Initializing the API
Configuring the HTTP Client
Getting Scores
Working with Scores

Installation ¶

To install WalkScore, just execute:

$ pip install walkscore-api

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:

urlfetch
requests
pycurl
urllib (Python standard library)

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 a LocationScore instance generated from a JSON string
.to_dict() which returns a dict 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 a LocationScore instance generated from a dict