API Reference

WalkScoreAPI

class WalkScoreAPI(api_key=None, http_client=None, proxy=None, max_retries=None)[source]

The Python object which exposes the WalkScore API’s functionality.

Parameters

  • api_key (str / None) – The API key provided by WalkScore used to authenticate your application. If None or not specified will default to the WALKSCORE_API_KEY environment variable if present, and None if not.

  • http_client (HTTPClient) –

    The HTTP client instance to use for the execution of requests. If not overridden, will default to urlfetch, requests, pycurl, urllib2 in order based on whether they are available in the environment.

    Tip

    You can override the HTTP client by supplying a HTTPClient instance to the method.

  • proxy (str / None) – The URL to use as an HTTP proxy. Defaults to None.

  • max_retries (int) – Determines the maximum number of HTTP request attempts to make on network failure before giving up. If not specified, defaults to environment variable BACKOFF_DEFAULT_TRIES or 3 if not available.

get_score(latitude, longitude, address=None, return_transit_score=True, return_bike_score=True, max_retries=None)[source]

Retrieve the WalkScore, TransitScore, and/or BikeScore for a given location from the WalkScore API.

Parameters

  • latitude (numeric) – The latitude of the location whose score(s) should be retrieved.

  • longitude (numeric) – The longitude of the location whose score(s) should be retrieved.

  • address (str / None) – The address whose score(s) should be retrieved. Defaults to None.

  • return_transit_score (bool) – If True, will return the location’s TransitScore. Defaults to True.

  • return_bike_score (bool) – If True, will return the location’s BikeScore. Defaults to True.

  • max_retries (None / int) – The maximum number of retries to attempt if the WalkScore API times out or otherwise fails to return a response. If None, will apply the default the configured when initializing the WalkScore API object. To suppress all retries, set to 0. Defaults to None.

Returns

The location’s WalkScore, TransitScore, and BikeScore with meta-data.

Return type

LocationScore

Raises
property api_key

The API key used to sign requests made against the API.

Return type

str / None

property http_client

The object instance to use as the HTTP client to make HTTP requests against the WalkScore API.

Return type

HTTPClient

property max_retries

The number of attempts to make on network connectivity-related API failures.

Return type

int

property proxy

The URL to use as a proxy for requests made to the WalkScore API.

Return type

str / None

LocationScore

class LocationScore(address=None, original_latitude=None, original_longitude=None, status=None, walk_score=None, walk_description=None, walk_updated=None, transit_score=None, transit_description=None, transit_summary=None, bike_score=None, bike_description=None, logo_url=None, more_info_icon=None, more_info_link=None, help_link=None, snapped_latitude=None, snapped_longitude=None, property_page_link=None)[source]

Object representation of a location’s scoring data returned from the WalkScore API.

Parameters

  • address (str / None) – The address originally supplied to the WalkScore API. Defaults to None.

  • original_latitude (numeric / None) – The latitude value originally supplied to the WalkScore API. Defaults to None.

  • original_longitude (numeric / None) – The longitude value originally supplied to the WalkScore API. Defaults to None.

  • status (int / None) – The status returned from the WalkScore API. Defaults to None.

  • walk_score (int / None) – The WalkScore for the location. Deafults to None

  • walk_description (str / None) – An English characterization of the WalkScore, e.g. “Somewhat Walkable”. Defaults to None.

  • walk_updated (datetime / None) – The timestamp when the WalkScore was calculated. Defaults to None

  • transit_score (int / None) – The TransitScore for the location. Deafults to None

  • transit_description (str / None) – An English characterization of the TransitScore, e.g. “Rider’s Paradise”. Defaults to None.

  • transit_summary (str / None) – Notes on the transit options accessible from the location. Defaults to None.

  • bike_score (int / None) – The BikeScore for the location. Deafults to None

  • bike_description (str / None) – An English characterization of the BikeScore, e.g. “Very Bikeable”. Defaults to None.

  • logo_url (str / None) – The URL of the WalkScore logo. Defaults to None.

  • more_info_icon (str / None) – The URL to the icon to use when linking to more information. Defaults to None.

  • more_info_link (str / None) – The URL to link to when providing more information. Defaults to None.

  • help_link (str / None) – A link to the “How Walk Score Works” page. Defaults to None.

  • snapped_latitude (numeric / None) – The latitude for the location, snapped to a grid of approximately 500 ft. by 500 ft. Defaults to None.

  • snapped_longitude (numeric / None) – The longitude for the location, snapped to a grid of approximately 500 ft. by 500 ft. Defaults to None.

  • property_page_link (str / None) – The URL to the walkscore.com map and score for the location. Defaults to None.

classmethod from_dict(obj, api_compatible=False)[source]

Create a LocationScore instance from a dict representation.

Parameters

  • obj (dict) – The dict representation of the location score.

  • api_compatible (bool) – If True, expects obj to be a dict whose structure is compatible with the JSON object returned by the WalkScore API. If False, expects a slightly more normalized dict representation. Defaults to False.

Returns

LocationScore representation of obj.

Return type

LocationScore

classmethod from_json(obj, api_compatible=False)[source]

Create a LocationScore instance from a JSON representation.

Parameters

  • obj (str or bytes) – The JSON representation of the location score.

  • api_compatible (bool) – If True, expects obj to be a JSON object whose structure is compatible with the JSON object returned by the WalkScore API. If False, expects a slightly more normalized representation. Defaults to False.

Returns

LocationScore representation of obj.

Return type

LocationScore

to_dict(api_compatible=False)[source]

Serialize the LocationScore to a dict.

Parameters

api_compatible (bool) – If True, returns a dict whose structure is compatible with the JSON object returned by the WalkScore API. If False, returns a slightly more normalized dict representation. Defaults to False.

Returns

dict representation of the object

Return type

dict

to_json(api_compatible=False)[source]

Serialize the LocationScore to a JSON string.

Parameters

api_compatible (bool) – If True, returns a JSON object whose structure is compatible with the JSON object returned by the WalkScore API. If False, returns a slightly more normalized structure. Defaults to False.

Returns

str representation of a JSON object

Return type

str

property address

The original address supplied for the LocationScore.

Return type

str

property bike_description

A textual description of the location’s bike-ability.

Return type

str

property bike_score

The TransitScore for the location, measuring bike-ability on a scale from 0 to 100.

Return type

int

URL to the “How WalkScore Works” page.

Return type

str

property logo_url

URL to the WalkScore logo.

Return type

str

property more_info_icon

URL to the question mark icon to display next to the Score.

Return type

str

URL for the question mark displayed next to the Score to link to.

Return type

str

property original_coordinates

The coordinates of the location as originally supplied.

Return type

tuple of longitude and latitude as float values

property original_latitude

The latitude of the location as originally supplied.

Return type

float

property original_longitude

The longitude of the location as originally supplied.

Return type

float

property property_page_link

URL to the walkscore.com score and map for the location.

Return type

str

property snapped_coordinates

The coordinates of the location as returned by the API.

Return type

tuple of longitude and latitude as float values

property snapped_latitude

The latitude of the location as returned by the API.

Return type

float

property snapped_longitude

The longitude of the location as returned by the API.

Return type

float

property status

Status Code of the result.

Return type

int

property transit_description

A textual description of the location’s ease-of-transit.

Return type

str

property transit_score

The TransitScore for the location, measuring ease-of-transit on a scale from 0 to 100.

Return type

int

property transit_summary

A textual summary of the location’s ease-of-transit.

Return type

str

property walk_description

A textual description of the location’s walkability.

Return type

str

property walk_score

The WalkScore for the location, measuring walkability on a scale from 0 to 100.

Return type

int

property walk_updated

The timestamp for when the location’s WalkScore was last updated.

Return type

datetime

HTTPClient

class HTTPClient(verify_ssl_certs=True, proxy=None)[source]

Base class that provides HTTP connectivity.

close()[source]

Closes an existing HTTP connection/session.

request(method, url, parameters=None, headers=None, request_body=None)[source]

Execute a standard HTTP request.

Parameters

  • method (str) – The HTTP method to use for the request. Accepts GET, HEAD, POST, PATCH, PUT, or DELETE.

  • url (str) – The URL to execute the request against.

  • parameters (dict / None) – URL parameters to submit with the request. Defaults to None.

  • headers (dict / None) – HTTP headers to submit with the request. Defaults to None.

  • request_body (None / dict / str / bytes) – The data to supply in the body of the request. Defaults to None.

Returns

The content of the HTTP response, the status code of the HTTP response, and the headers of the HTTP response.

Return type

tuple of bytes, int, and dict

Raises
request_with_retries(method, url, parameters=None, headers=None, request_body=None)[source]

Execute a standard HTTP request with automatic retries on failure.

Parameters

  • method (str) – The HTTP method to use for the request. Accepts GET, HEAD, POST, PATCH, PUT, or DELETE.

  • url (str) – The URL to execute the request against.

  • parameters (dict / None) – URL parameters to submit with the request. Defaults to None.

  • headers (dict / None) – HTTP headers to submit with the request. Defaults to None.

  • request_body (None / dict / str / bytes) – The data to supply in the body of the request. Defaults to None.

Note

This method will apply an exponential backoff strategy to retry the API request if it times out. By default:

  • requests that can be retried will be retried up to 3 times, but this can be overridden by setting a BACKOFF_DEFAULT_TRIES environment variable with the maximum number of attempts to make

  • there is no maximum delay to wait before final failure, but this can be overridden by setting a BACKOFF_DEFAULT_DELAY environment variable with the maximum number of seconds to wait (across all attempts) before failing.

Raises

  • ValueError – if method is not either GET, HEAD, POST, PATCH, PUT or DELETE

  • ValueError – if url is not a valid URL

  • HTTPTimeoutError – if the request times out after repeated attempts

  • SSLError – if the request fails SSL certificate verification

  • WalkScoreError – or sub-classes for other errors returned by the API