OpenStreetMap¶

class OpenStreetMap(opts)¶

An address search provider for Open Street Map.

Arguments:

opts.api_url (string) – The URL of the Open Street Map API. Defaults to ‘http://open.mapquestapi.com/nominatim/v1/search.php‘.
opts.extract_address_label (function) – Function that extracts a human-friendly label from an Open Street Map API result. See OpenStreetMap.extract_address_label() for the function signature and default implementation.
opts.extract_address_data (function) – Function that extracts data to store on a contact from an Open Street Map API result. See OpenStreetMap.extract_address_data() for the function signature and default implementation.
hard_boundary (boolean) – Whether to limit results to a fixed bounding box. Defaults to true.
address_limit (integer) – Maximum number of search results to return. Defaults to 30.
bounding_box (array) – Bounding box to limit search results to. Should be provided in the form [left_edge, top_edge, right_edge, bottom_edge], e.g. ["-18.3273", "-33.7652", "18.937", "-34.3329"] for South Africa. Defaults to ["-180.0", "90.0", "180.0", "-90.0"] for worldwide search.

See http://open.mapquestapi.com/nominatim/ for a complete description of the Open Street Map search API.

static extract_address(result)¶

Takes a result from the OpenStreetMap API and returns a AddressResult() for it.

Arguments:	result (object) – A raw OpenStreetMap result.
Returns:	An `Addressresult()`.

Calls OpenStreetMap.extract_address_label() and OpenStreetMap.extract_address_data() for the label and data respectively.

static extract_address_data(result)¶

Extracts address data to store on a contact when an address is selected. See LocationState.store_contact_data() for a description of how this data is stored.

Returns the object:

{
    formatted_address: result.display_name
}

May be overriden using the extract_address_data class option.

Arguments:	result (object) – A location result from the Open Street Map API.
Returns object:	An object of key-value pairs to store in contact data.

static extract_address_label(result)¶

Returns the value of result.display_name as a human-friendly display name for an Open Street Map location result.

May be overriden using the extract_address_label class option.

Arguments:	result (object) – A location result from the Open Street Map API.
Return string:	The label to display for this result.

static init()¶

Initialization function invoked during state initialization.

Arguments:	im (InteractionMachine) – The state’s `InteractionMachine()` instance.

static search(query_text)¶

Return an ordered list of locations matching the query via a promise that is fulfilled when the search results are ready.

Returns an empty list if an error occurs while accessing the Open Street Map API.

Arguments:	query_text (string) – The search query.
Returns:	A promise that yields the list of search results.

fixture(opts)¶

Returns an HTTP resource fixture for an OpenStreetMap location query.

Arguments:

opts.query (string) – The address that is to be queried. Required.
opts.address_list (array of strings) – A list of display_name``s that should be sent in the response. If response_data is included, this will be ignored. Defaults to ``[].
hard_boundary (boolean) – Whether the request should limit results to a fixed bounding box. Defaults to true.
address_limit (integer) – The maximum number of search results that should be requested. Defaults to 30.
bounding_box (array) – The bounding box to submit in the search request. Should be provided in the form [left_edge, top_edge, right_edge, bottom_edge], e.g. ["-18.3273", "-33.7652", "18.937", "-34.3329"] for South Africa. Defaults to ["-180.0", "90.0", "180.0", "-90.0"] for worldwide search.
opts.request_url (string) – URL for the HTTP request. Defaults to "http://open.mapquestapi.com/nominatim/v1/search.php".
opts.response_data (object) –
An object that represents the response from the OpenStreetMap API. This overrides the response data generated from opts.address_list. Example response data:
```
[
    {
        display_name: "1 Baker Street",
    },
    {
        display_name: "2 Baker Street",
    },
]
```

Usage:

tester
    .setup(function(api) {
        api.http.fixtures.add(
            OpenStreetMap.fixture({
                request: "New Street",
                address_list: [
                    "New Street 1", "New Street 2",
                ],
            });
        );
    });