mirror of
https://github.com/osm-search/Nominatim.git
synced 2026-03-11 13:24:07 +00:00
docs: documentation of API classes
This commit is contained in:
Sarah Hoffmann
@@ -30,11 +30,31 @@ from nominatim.api.results import DetailedResult, ReverseResult, SearchResults
|
||||
|
||||
|
||||
class NominatimAPIAsync:
|
||||
""" API loader asynchornous version.
|
||||
""" The main frontend to the Nominatim database implements the
|
||||
functions for lookup, forward and reverse geocoding using
|
||||
asynchronous functions.
|
||||
|
||||
This class shares most of the functions with its synchronous
|
||||
version. There are some additional functions or parameters,
|
||||
which are documented below.
|
||||
"""
|
||||
def __init__(self, project_dir: Path,
|
||||
environ: Optional[Mapping[str, str]] = None,
|
||||
loop: Optional[asyncio.AbstractEventLoop] = None) -> None:
|
||||
""" Initiate a new frontend object with synchronous API functions.
|
||||
|
||||
Parameters:
|
||||
project_dir: Path to the
|
||||
[project directory](../admin/Import.md#creating-the-project-directory)
|
||||
of the local Nominatim installation.
|
||||
environ: Mapping of additional
|
||||
[configuration parameters](../customize/Settings.md).
|
||||
These will override default configuration and configuration
|
||||
from the project directory.
|
||||
loop: The asyncio event loop that will be used when calling
|
||||
functions. Only needed, when a custom event loop is used
|
||||
and the Python version is 3.9 or earlier.
|
||||
"""
|
||||
self.config = Configuration(project_dir, environ)
|
||||
self.query_timeout = self.config.get_int('QUERY_TIMEOUT') \
|
||||
if self.config.QUERY_TIMEOUT else None
|
||||
@@ -50,7 +70,7 @@ class NominatimAPIAsync:
|
||||
|
||||
|
||||
async def setup_database(self) -> None:
|
||||
""" Set up the engine and connection parameters.
|
||||
""" Set up the SQL engine and connections.
|
||||
|
||||
This function will be implicitly called when the database is
|
||||
accessed for the first time. You may also call it explicitly to
|
||||
@@ -288,19 +308,33 @@ class NominatimAPIAsync:
|
||||
|
||||
|
||||
class NominatimAPI:
|
||||
""" API loader, synchronous version.
|
||||
""" This class provides a thin synchronous wrapper around the asynchronous
|
||||
Nominatim functions. It creates its own event loop and runs each
|
||||
synchronous function call to completion using that loop.
|
||||
"""
|
||||
|
||||
def __init__(self, project_dir: Path,
|
||||
environ: Optional[Mapping[str, str]] = None) -> None:
|
||||
""" Initiate a new frontend object with synchronous API functions.
|
||||
|
||||
Parameters:
|
||||
project_dir: Path to the
|
||||
[project directory](../admin/Import.md#creating-the-project-directory)
|
||||
of the local Nominatim installation.
|
||||
environ: Mapping of additional
|
||||
[configuration parameters](../customize/Settings.md).
|
||||
These will override default configuration and configuration
|
||||
from the project directory.
|
||||
"""
|
||||
self._loop = asyncio.new_event_loop()
|
||||
self._async_api = NominatimAPIAsync(project_dir, environ, loop=self._loop)
|
||||
|
||||
|
||||
def close(self) -> None:
|
||||
""" Close all active connections to the database. The NominatimAPIAsync
|
||||
object remains usable after closing. If a new API functions is
|
||||
called, new connections are created.
|
||||
""" Close all active connections to the database.
|
||||
|
||||
This function also closes the asynchronous worker loop making
|
||||
the NominatimAPI object unusuable.
|
||||
"""
|
||||
self._loop.run_until_complete(self._async_api.close())
|
||||
self._loop.close()
|
||||
@@ -308,18 +342,108 @@ class NominatimAPI:
|
||||
|
||||
@property
|
||||
def config(self) -> Configuration:
|
||||
""" Return the configuration used by the API.
|
||||
""" Provide read-only access to the [configuration](#Configuration)
|
||||
used by the API.
|
||||
"""
|
||||
return self._async_api.config
|
||||
|
||||
def status(self) -> StatusResult:
|
||||
""" Return the status of the database.
|
||||
""" Return the status of the database as a dataclass object
|
||||
with the fields described below.
|
||||
|
||||
Returns:
|
||||
status(int): A status code as described on the status page.
|
||||
message(str): Either 'OK' or a human-readable message of the
|
||||
problem encountered.
|
||||
software_version(tuple): A tuple with the version of the
|
||||
Nominatim library consisting of (major, minor, patch, db-patch)
|
||||
version.
|
||||
database_version(tuple): A tuple with the version of the library
|
||||
which was used for the import or last migration.
|
||||
Also consists of (major, minor, patch, db-patch).
|
||||
data_updated(datetime): Timestamp with the age of the data.
|
||||
"""
|
||||
return self._loop.run_until_complete(self._async_api.status())
|
||||
|
||||
|
||||
def details(self, place: ntyp.PlaceRef, **params: Any) -> Optional[DetailedResult]:
|
||||
""" Get detailed information about a place in the database.
|
||||
|
||||
The result is a dataclass object with the fields described below
|
||||
or `None` if the place could not be found in the database.
|
||||
|
||||
Parameters:
|
||||
place: Description of the place to look up. See PlaceRef below
|
||||
for the various ways to reference a place.
|
||||
|
||||
Other parameters:
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
parent_place_id (Optional(int]): Internal ID of the parent of this
|
||||
place. Only meaning full for POI-like objects (places with a
|
||||
rank_address of 30).
|
||||
linked_place_id (Optional[int]): Internal ID of the place this object
|
||||
linkes to. When this ID is set then there is no guarantee that
|
||||
the rest of the result information is complete.
|
||||
admin_level (int): Value of the `admin_level` OSM tag. Only meaningful
|
||||
for administrative boundary objects.
|
||||
indexed_date (datetime): Timestamp when the place was last updated.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
"""
|
||||
return self._loop.run_until_complete(self._async_api.details(place, **params))
|
||||
|
||||
@@ -328,6 +452,74 @@ class NominatimAPI:
|
||||
""" Get simple information about a list of places.
|
||||
|
||||
Returns a list of place information for all IDs that were found.
|
||||
Each result is a dataclass with the fields detailed below.
|
||||
|
||||
Parameters:
|
||||
places: List of descriptions of the place to look up. See PlaceRef below
|
||||
for the various ways to reference a place.
|
||||
|
||||
Other parameters:
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
bbox (Bbox): Bounding box of the full geometry of the place.
|
||||
If the place is a single point, then the size of the bounding
|
||||
box is guessed according to the type of place.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
"""
|
||||
return self._loop.run_until_complete(self._async_api.lookup(places, **params))
|
||||
|
||||
@@ -335,14 +527,175 @@ class NominatimAPI:
|
||||
def reverse(self, coord: ntyp.AnyPoint, **params: Any) -> Optional[ReverseResult]:
|
||||
""" Find a place by its coordinates. Also known as reverse geocoding.
|
||||
|
||||
Returns the closest result that can be found or None if
|
||||
no place matches the given criteria.
|
||||
Returns the closest result that can be found or `None` if
|
||||
no place matches the given criteria. The result is a dataclass
|
||||
with the fields as detailed below.
|
||||
|
||||
Parameters:
|
||||
coord: Coordinate to lookup the place for as a Point
|
||||
or a tuple (x, y). Must be in WGS84 projection.
|
||||
|
||||
Other parameters:
|
||||
max_rank (int): Highest address rank to return. Can be used to
|
||||
restrict search to streets or settlements.
|
||||
layers (enum): Defines the kind of data to take into account.
|
||||
See description of layers below. (Default: addresses and POIs)
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
bbox (Bbox): Bounding box of the full geometry of the place.
|
||||
If the place is a single point, then the size of the bounding
|
||||
box is guessed according to the type of place.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
distance (Optional[float]): Distance in degree from the input point.
|
||||
"""
|
||||
return self._loop.run_until_complete(self._async_api.reverse(coord, **params))
|
||||
|
||||
|
||||
def search(self, query: str, **params: Any) -> SearchResults:
|
||||
""" Find a place by free-text search. Also known as forward geocoding.
|
||||
|
||||
Parameters:
|
||||
query: Free-form text query searching for a place.
|
||||
|
||||
Other parameters:
|
||||
max_results (int): Maximum number of results to return. The
|
||||
actual number of results may be less. (Default: 10)
|
||||
min_rank (int): Lowest [address rank](../customize/Ranking.md#address-rank) to return.
|
||||
max_rank (int): Highest address rank to return.
|
||||
layers (enum): Defines the kind of data to take into account.
|
||||
See description of layers below. (Default: addresses and POIs)
|
||||
countries (list[str]): Restrict search to countries with the given
|
||||
ISO 3166-1 alpha-2 country code. An empty list (the default)
|
||||
disables this filter.
|
||||
excluded (list[int]): A list of internal IDs of places to exclude
|
||||
from the search.
|
||||
viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
|
||||
bounded_viewbox (bool): Consider the bounding box given in `viewbox`
|
||||
as a filter and return only results within the bounding box.
|
||||
near (Optional[Point]): Focus search around the given point and
|
||||
return results ordered by distance to the given point.
|
||||
near_radius (Optional[float]): Restrict results to results within
|
||||
the given distance in degrees of `near` point. Ignored, when
|
||||
`near` is not set.
|
||||
categories (list[tuple]): Restrict search to places of the given
|
||||
categories. The category is the main OSM tag assigned to each
|
||||
place. An empty list (the default) disables this filter.
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
bbox (Bbox): Bounding box of the full geometry of the place.
|
||||
If the place is a single point, then the size of the bounding
|
||||
box is guessed according to the type of place.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
"""
|
||||
return self._loop.run_until_complete(
|
||||
self._async_api.search(query, **params))
|
||||
@@ -358,6 +711,104 @@ class NominatimAPI:
|
||||
postalcode: Optional[str] = None,
|
||||
**params: Any) -> SearchResults:
|
||||
""" Find an address using structured search.
|
||||
|
||||
Parameters:
|
||||
amenity: Name of a POI.
|
||||
street: Street and optionally housenumber of the address. If the address
|
||||
does not have a street, then the place the housenumber references to.
|
||||
city: Postal city of the address.
|
||||
county: County equivalent of the address. Does not exist in all
|
||||
jurisdictions.
|
||||
state: State or province of the address.
|
||||
country: Country with its full name or its ISO 3166-1 alpha-2 country code.
|
||||
Do not use together with the country_code filter.
|
||||
postalcode: Post code or ZIP for the place.
|
||||
|
||||
Other parameters:
|
||||
max_results (int): Maximum number of results to return. The
|
||||
actual number of results may be less. (Default: 10)
|
||||
min_rank (int): Lowest [address rank](../customize/Ranking.md#address-rank) to return.
|
||||
max_rank (int): Highest address rank to return.
|
||||
layers (enum): Defines the kind of data to take into account.
|
||||
See description of layers below. (Default: addresses and POIs)
|
||||
countries (list[str]): Restrict search to countries with the given
|
||||
ISO 3166-1 alpha-2 country code. An empty list (the default)
|
||||
disables this filter. Do not use, when the country parameter
|
||||
is used.
|
||||
excluded (list[int]): A list of internal IDs of places to exclude
|
||||
from the search.
|
||||
viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
|
||||
bounded_viewbox (bool): Consider the bounding box given in `viewbox`
|
||||
as a filter and return only results within the bounding box.
|
||||
near (Optional[Point]): Focus search around the given point and
|
||||
return results ordered by distance to the given point.
|
||||
near_radius (Optional[float]): Restrict results to results within
|
||||
the given distance in degrees of `near` point. Ignored, when
|
||||
`near` is not set.
|
||||
categories (list[tuple]): Restrict search to places of the given
|
||||
categories. The category is the main OSM tag assigned to each
|
||||
place. An empty list (the default) disables this filter.
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
bbox (Bbox): Bounding box of the full geometry of the place.
|
||||
If the place is a single point, then the size of the bounding
|
||||
box is guessed according to the type of place.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
"""
|
||||
return self._loop.run_until_complete(
|
||||
self._async_api.search_address(amenity, street, city, county,
|
||||
@@ -368,9 +819,99 @@ class NominatimAPI:
|
||||
near_query: Optional[str] = None,
|
||||
**params: Any) -> SearchResults:
|
||||
""" Find an object of a certain category near another place.
|
||||
|
||||
The near place may either be given as an unstructured search
|
||||
query in itself or as a geographic area through the
|
||||
viewbox or near parameters.
|
||||
|
||||
Parameters:
|
||||
categories: Restrict search to places of the given
|
||||
categories. The category is the main OSM tag assigned to each
|
||||
place.
|
||||
near_query: Optional free-text query to define the are to
|
||||
restrict search to.
|
||||
|
||||
Other parameters:
|
||||
max_results (int): Maximum number of results to return. The
|
||||
actual number of results may be less. (Default: 10)
|
||||
min_rank (int): Lowest [address rank](../customize/Ranking.md#address-rank) to return.
|
||||
max_rank (int): Highest address rank to return.
|
||||
layers (enum): Defines the kind of data to take into account.
|
||||
See description of layers below. (Default: addresses and POIs)
|
||||
countries (list[str]): Restrict search to countries with the given
|
||||
ISO 3166-1 alpha-2 country code. An empty list (the default)
|
||||
disables this filter.
|
||||
excluded (list[int]): A list of internal IDs of places to exclude
|
||||
from the search.
|
||||
viewbox (Optional[Bbox]): Bounding box of an area to focus search on.
|
||||
bounded_viewbox (bool): Consider the bounding box given in `viewbox`
|
||||
as a filter and return only results within the bounding box.
|
||||
near (Optional[Point]): Focus search around the given point and
|
||||
return results ordered by distance to the given point.
|
||||
near_radius (Optional[float]): Restrict results to results within
|
||||
the given distance in degrees of `near` point. Ignored, when
|
||||
`near` is not set.
|
||||
geometry_output (enum): Add the full geometry of the place to the result.
|
||||
Multiple formats may be selected. Note that geometries can become
|
||||
quite large. (Default: none)
|
||||
geometry_simplification (float): Simplification factor to use on
|
||||
the geometries before returning them. The factor expresses
|
||||
the tolerance in degrees from which the geometry may differ.
|
||||
Topology is preserved. (Default: 0.0)
|
||||
address_details (bool): Add detailed information about the places
|
||||
that make up the address of the requested object. (Default: False)
|
||||
linked_places (bool): Add detailed information about the places
|
||||
that link to the result. (Default: False)
|
||||
parented_places (bool): Add detailed information about all places
|
||||
for which the requested object is a parent, i.e. all places for
|
||||
which the object provides the address details.
|
||||
Only POI places can have parents. (Default: False)
|
||||
keywords (bool): Add detailed information about the search terms
|
||||
used for this place.
|
||||
|
||||
Returns:
|
||||
source_table (enum): Data source of the place. See below for possible values.
|
||||
category (tuple): A tuple of two strings with the primary OSM tag
|
||||
and value.
|
||||
centroid (Point): Point position of the place.
|
||||
place_id (Optional[int]): Internal ID of the place. This ID may differ
|
||||
for the same place between different installations.
|
||||
osm_object (Optional[tuple]): OSM type and ID of the place, if available.
|
||||
names (Optional[dict]): Dictionary of names of the place. Keys are
|
||||
usually the corresponding OSM tag keys.
|
||||
address (Optional[dict]): Dictionary of address parts directly
|
||||
attributed to the place. Keys are usually the corresponding
|
||||
OSM tag keys with the `addr:` prefix removed.
|
||||
extratags (Optional[dict]): Dictionary of additional attributes for
|
||||
the place. Usually OSM tag keys and values.
|
||||
housenumber (Optional[str]): House number of the place, normalised
|
||||
for lookup. To get the house number in its original spelling,
|
||||
use `address['housenumber']`.
|
||||
postcode (Optional[str]): Computed postcode for the place. To get
|
||||
directly attributed postcodes, use `address['postcode']` instead.
|
||||
wikipedia (Optional[str]): Reference to a wikipedia site for the place.
|
||||
The string has the format <language code>:<wikipedia title>.
|
||||
rank_address (int): [Address rank](../customize/Ranking.md#address-rank).
|
||||
rank_search (int): [Search rank](../customize/Ranking.md#search-rank).
|
||||
importance (Optional[float]): Relative importance of the place. This is a measure
|
||||
how likely the place will be searched for.
|
||||
country_code (Optional[str]): Country the feature is in as
|
||||
ISO 3166-1 alpha-2 country code.
|
||||
address_rows (Optional[AddressLines]): List of places that make up the
|
||||
computed address. `None` when `address_details` parameter was False.
|
||||
linked_rows (Optional[AddressLines]): List of places that link to the object.
|
||||
`None` when `linked_places` parameter was False.
|
||||
parented_rows (Optional[AddressLines]): List of direct children of the place.
|
||||
`None` when `parented_places` parameter was False.
|
||||
name_keywords (Optional[WordInfos]): List of search words for the name of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
address_keywords (Optional[WordInfos]): List of search word for the address of
|
||||
the place. `None` when `keywords` parameter is set to False.
|
||||
bbox (Bbox): Bounding box of the full geometry of the place.
|
||||
If the place is a single point, then the size of the bounding
|
||||
box is guessed according to the type of place.
|
||||
geometry (dict): Dictionary containing the full geometry of the place
|
||||
in the formats requested in the `geometry_output` parameter.
|
||||
"""
|
||||
return self._loop.run_until_complete(
|
||||
self._async_api.search_category(categories, near_query, **params))
|
||||
|
||||
@@ -419,7 +419,7 @@ class SearchDetails(LookupDetails):
|
||||
"""
|
||||
excluded: List[int] = dataclasses.field(default_factory=list,
|
||||
metadata={'transform': format_excluded})
|
||||
""" List of OSM objects to exclude from the results. Currenlty only
|
||||
""" List of OSM objects to exclude from the results. Currently only
|
||||
works when the internal place ID is given.
|
||||
An empty list (the default) will disable this filter.
|
||||
"""
|
||||
|
||||
Reference in New Issue
Block a user