Stadia Maps Python API Client

https://github.com/stadiamaps/stadiamaps-api-py
Admin
Stadia Maps Python API Client provides a Python SDK for interacting with Stadia Maps Geospatial...
Tokens:109,374
Snippets:632
Trust Score:8.2
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Python example: Create and use ExtendedDirectionsOptions

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/ExtendedDirectionsOptions.md

Shows how to import ExtendedDirectionsOptions, create an instance from a JSON string, convert to dict, and back. The example includes placeholder JSON and prints the JSON representation.

```python
from stadiamaps.models.extended_directions_options import ExtendedDirectionsOptions

# TODO update the JSON string below
json = "{}"
# create an instance of ExtendedDirectionsOptions from a JSON string
extended_directions_options_instance = ExtendedDirectionsOptions.from_json(json)
# print the JSON string representation of the object
print(ExtendedDirectionsOptions.to_json())

# convert the object into a dict
extended_directions_options_dict = extended_directions_options_instance.to_dict()
# create an instance of ExtendedDirectionsOptions from a dict
extended_directions_options_from_dict = ExtendedDirectionsOptions.from_dict(extended_directions_options_dict)
```

--------------------------------

### Python example for WofContextComponent

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/WofContextComponent.md

Shows how to create an instance from a JSON string and from a dict, and how to print the JSON string representation.

```python
from stadiamaps.models.wof_context_component import WofContextComponent

# TODO update the JSON string below
json = "{}"
# create an instance of WofContextComponent from a JSON string
wof_context_component_instance = WofContextComponent.from_json(json)
# print the JSON string representation of the object
print(WofContextComponent.to_json())

# convert the object into a dict
wof_context_component_dict = wof_context_component_instance.to_dict()
# create an instance of WofContextComponent from a dict
wof_context_component_from_dict = WofContextComponent.from_dict(wof_context_component_dict)
```

--------------------------------

### Python example for SearchStructuredBulkQuery

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/SearchStructuredBulkQuery.md

Shows how to import SearchStructuredBulkQuery, create an instance from a JSON string, print its JSON representation, and convert to/from a dict.

```python
from stadiamaps.models.search_structured_bulk_query import SearchStructuredBulkQuery

# TODO update the JSON string below
json = "{}"
# create an instance of SearchStructuredBulkQuery from a JSON string
search_structured_bulk_query_instance = SearchStructuredBulkQuery.from_json(json)
# print the JSON string representation of the object
print(SearchStructuredBulkQuery.to_json())

# convert the object into a dict
search_structured_bulk_query_dict = search_structured_bulk_query_instance.to_dict()
# create an instance of SearchStructuredBulkQuery from a dict
search_structured_bulk_query_from_dict = SearchStructuredBulkQuery.from_dict(search_structured_bulk_query_dict)
```

--------------------------------

### Usage example: create and convert OsrmRouteStep instance

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/OsrmRouteStep.md

Shows typical usage of the OsrmRouteStep model. Import the class, create an instance from a JSON string using from_json, print the JSON representation with to_json, convert to a dictionary with to_dict, and create an instance from that dictionary using from_dict. The JSON string in the example is a placeholder to update.

```python
from stadiamaps.models.osrm_route_step import OsrmRouteStep

# TODO update the JSON string below
json = "{}"
# create an instance of OsrmRouteStep from a JSON string
osrm_route_step_instance = OsrmRouteStep.from_json(json)
# print the JSON string representation of the object
print(OsrmRouteStep.to_json())

# convert the object into a dict
osrm_route_step_dict = osrm_route_step_instance.to_dict()
# create an instance of OsrmRouteStep from a dict
osrm_route_step_from_dict = OsrmRouteStep.from_dict(osrm_route_step_dict)

```

--------------------------------

### Python example for OsrmViaWaypoint

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/OsrmViaWaypoint.md

Shows how to create an OsrmViaWaypoint instance from a JSON string, print its JSON representation, and convert to/from a dict.

```python
from stadiamaps.models.osrm_via_waypoint import OsrmViaWaypoint

# TODO update the JSON string below
json = "{}"
# create an instance of OsrmViaWaypoint from a JSON string
osrm_via_waypoint_instance = OsrmViaWaypoint.from_json(json)
# print the JSON string representation of the object
print(OsrmViaWaypoint.to_json())

# convert the object into a dict
osrm_via_waypoint_dict = osrm_via_waypoint_instance.to_dict()
# create an instance of OsrmViaWaypoint from a dict
osrm_via_waypoint_from_dict = OsrmViaWaypoint.from_dict(osrm_via_waypoint_dict)
```

--------------------------------

### Structured geocoding with ApiKeyAuth

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Example of using the search_structured endpoint with API key authentication. The host defaults to https://api.stadiamaps.com, and the API key is set via the environment variable API_KEY. The example imports the necessary models and shows how to configure the client.

```python
import stadiamaps
from stadiamaps.models.geocode_response import GeocodeResponse
from stadiamaps.models.geocoding_layer import GeocodingLayer
from stadiamaps.models.geocoding_source import GeocodingSource
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'
```

--------------------------------

### OsrmBannerInstruction Python example

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/OsrmBannerInstruction.md

Shows how to import OsrmBannerInstruction, create an instance from a JSON string or dict, and convert between JSON and dict representations.

```python
from stadiamaps.models.osrm_banner_instruction import OsrmBannerInstruction

# TODO update the JSON string below
json = "{}"
# create an instance of OsrmBannerInstruction from a JSON string
osrm_banner_instruction_instance = OsrmBannerInstruction.from_json(json)
# print the JSON string representation of the object
print(OsrmBannerInstruction.to_json())

# convert the object into a dict
osrm_banner_instruction_dict = osrm_banner_instruction_instance.to_dict()
# create an instance of OsrmBannerInstruction from a dict
osrm_banner_instruction_from_dict = OsrmBannerInstruction.from_dict(osrm_banner_instruction_dict)
```

--------------------------------

### GET /geocoding/v2/autocomplete

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Search and geocode quickly based on partial input.

```APIDOC
## GET /geocoding/v2/autocomplete

### Description
Search and geocode quickly based on partial input.

### Method
GET

### Endpoint
/geocoding/v2/autocomplete
```

--------------------------------

### GET /geocoding/v2/place_details

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Retrieve detailed information about a place by its GID.

```APIDOC
## GET /geocoding/v2/place_details

### Description
Retrieve detailed information about a place by its GID.

### Method
GET

### Endpoint
/geocoding/v2/place_details
```

--------------------------------

### GET /geocoding/v2/place

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Retrieve detailed information about a place by its GID.

```APIDOC
## [GET] /geocoding/v2/place

### Description
Retrieve detailed information about a place by its GID.

### Method
GET

### Endpoint
/geocoding/v2/place

### Parameters
#### Query Parameters
- **ids** (List[str]) - Required - A list of GIDs to look up.
- **lang** (str) - Optional - A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically.

### Request Example
```
GET /geocoding/v2/place?ids=["whosonfirst:locality:102026327"]&lang=lang_example
```

### Response
#### Success Response (200)
- **GeocodeResponseEnvelopePropertiesV2** - A GeoJSON FeatureCollection with the results.

#### Response Example
```json
{
  "type": "FeatureCollection",
  "features": []
}
```

### Error Responses
- **400** - A response with a description of why the request is malformed.
- **500** - A response with a description of what went wrong internally.

### Authorization
ApiKeyAuth

### HTTP Request Headers
- **Content-Type**: Not defined
- **Accept**: application/json
```

--------------------------------

### GeocodingApi.search

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Example of using the GeocodingApi search method for forward geocoding.

```APIDOC
## [GET] /search

### Description
Search for location and other info using a place name or address (forward geocoding).

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **text** (str) - Required - The place name (address, venue name, etc.) to search for.
- **focus.point.lat** (float) - Optional - The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`.
- **focus.point.lon** (float) - Optional - The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`.
- **boundary.rect.min_lat** (float) - Optional - Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary.rect.max_lat** (float) - Optional - Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary.rect.min_lon** (float) - Optional - Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary.rect.max_lon** (float) - Optional - Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary.circle.lat** (float) - Optional - The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`.
- **boundary.circle.lon** (float) - Optional - The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`.
- **boundary.circle.radius** (float) - Optional - The radius of the circle (in kilometers) to limit the search to. Defaults to 50km (search) or 1km (reverse) if unspecified.
- **boundary.country** (List[str]) - Optional - A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format.
- **boundary.gid** (str) - Optional - The GID of an area to limit the search to.
- **layers** (List[GeocodingLayer]) - Optional - A list of layers to limit the search to.
- **sources** (List[GeocodingSource]) - Optional - A list of sources to limit the search to.
- **size** (int) - Optional - The maximum number of results to return.
- **lang** (str) - Optional - A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.

### Request Example
```python
import stadiamaps
from stadiamaps.models.geocode_response import GeocodeResponse
from stadiamaps.models.geocoding_layer import GeocodingLayer
from stadiamaps.models.geocoding_source import GeocodingSource
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)
    text = '1600 Pennsylvania Ave NW' # str | The place name (address, venue name, etc.) to search for.
    focus_point_lat = 3.4 # float | The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`. (optional)
    focus_point_lon = 3.4 # float | The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`. (optional)
    boundary_rect_min_lat = 3.4 # float | Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. (optional)
    boundary_rect_max_lat = 3.4 # float | Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. (optional)
    boundary_rect_min_lon = 3.4 # float | Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. (optional)
    boundary_rect_max_lon = 3.4 # float | Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. (optional)
    boundary_circle_lat = 3.4 # float | The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`. (optional)
    boundary_circle_lon = 3.4 # float | The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`. (optional)
    boundary_circle_radius = 3.4 # float | The radius of the circle (in kilometers) to limit the search to. Defaults to 50km (search) or 1km (reverse) if unspecified. (optional)
    boundary_country = ['boundary_country_example'] # List[str] | A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format. (optional)
    boundary_gid = 'boundary_gid_example' # str | The GID of an area to limit the search to. (optional)
    layers = [stadiamaps.GeocodingLayer()] # List[GeocodingLayer] | A list of layers to limit the search to. (optional)
    sources = [stadiamaps.GeocodingSource()] # List[GeocodingSource] | A list of sources to limit the search to. (optional)
    size = 56 # int | The maximum number of results to return. (optional)
    lang = 'lang_example' # str | A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English. (optional)

    try:
        # Search for location and other info using a place name or address (forward geocoding).
        api_response = api_instance.search(text, focus_point_lat=focus_point_lat, focus_point_lon=focus_point_lon, boundary_rect_min_lat=boundary_rect_min_lat, boundary_rect_max_lat=boundary_rect_max_lat, boundary_rect_min_lon=boundary_rect_min_lon, boundary_rect_max_lon=boundary_rect_max_lon, boundary_circle_lat=boundary_circle_lat, boundary_circle_lon=boundary_circle_lon, boundary_circle_radius=boundary_circle_radius, boundary_country=boundary_country, boundary_gid=boundary_gid, layers=layers, sources=sources, size=size, lang=lang)
        print("The response of GeocodingApi->search:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling GeocodingApi->search: %s\n" % e)
```

### Response
#### Success Response (200)
- **GeocodeResponse** - The geocoding response containing the search results.

#### Response Example
```python
# The response is a GeocodeResponse object. See the model definition for details.
```
```

--------------------------------

### GeocodingApi.autocomplete_v2

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Example of calling the autocomplete_v2 method of the GeocodingApi class in the stadiamaps Python SDK.

```APIDOC
## [POST] /geocoding/v2/search/autocomplete

### Description
Search and geocode quickly based on partial input.

### Method
POST

### Endpoint
/geocoding/v2/search/autocomplete

### Parameters
#### Path Parameters
None

#### Query Parameters
- **text** (string) - Required - The text to search for (the start of an address, place name, etc.).
- **focus_point_lat** (float) - Optional - The latitude of a focus point. If provided (along with longitude), the search results should be more locally relevant.
- **focus_point_lon** (float) - Optional - The longitude of a focus point. If provided (along with longitude), the search results should be more locally relevant.
- **layers** (array of LayerId) - Optional - A list of layers to limit the search to.
- **sources** (array of SourceId) - Optional - A list of sources to limit the search to.
- **boundary_gid** (string) - Optional - The GID of a region to limit the search to. Note: these are not stable for all datasets! For example, OSM features may be deleted and re-added with a new ID.
- **boundary_country** (array of string) - Optional - A list of comma-separated country codes in ISO 3116-1 alpha-2 or alpha-3 format. The search will be limited to these countries.
- **boundary_rect_min_lat** (float) - Optional - The minimum latitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_min_lon** (float) - Optional - The minimum longitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_max_lat** (float) - Optional - The maximum latitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_max_lon** (float) - Optional - The maximum longitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_circle_lat** (float) - Optional - The latitude of the center of a circle to limit the search to. NOTE: Requires boundary.circle.lon.
- **boundary_circle_lon** (float) - Optional - The longitude of the center of a circle to limit the search to. NOTE: Requires boundary.circle.lat.
- **boundary_circle_radius** (integer) - Optional - The radius of the circle (in kilometers) to limit the search to. NOTE: Requires the other boundary.circle parameters to take effect. Defaults to 50km if unspecified.
- **size** (integer) - Optional - The maximum number of items to return from a query.
- **lang** (string) - Optional - A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically.

### Request Example
```
{
  "text": "1600 Pennsylvania Ave NW",
  "focus_point_lat": 3.4,
  "focus_point_lon": 3.4,
  "layers": ["venue"],
  "sources": ["openstreetmap"],
  "boundary_gid": "boundary_gid_example",
  "boundary_country": ["US"],
  "boundary_rect_min_lat": 3.4,
  "boundary_rect_min_lon": 3.4,
  "boundary_rect_max_lat": 3.4,
  "boundary_rect_max_lon": 3.4,
  "boundary_circle_lat": 3.4,
  "boundary_circle_lon": 3.4,
  "boundary_circle_radius": 56,
  "size": 56,
  "lang": "en"
}
```

### Response
#### Success Response (200)
- **GeocodeResponseEnvelopePropertiesV2** - The response envelope containing geocoding results.

#### Response Example
```
{
  "geocoding": {
    "version": "2",
    "attribution": "...",
    "query": {
      "text": "1600 Pennsylvania Ave NW"
    },
    "engine": {
      "name": "...",
      "author": "...",
      "version": "..."
    },
    "timestamp": 1234567890
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-77.0365, 38.8977]
      },
      "properties": {
        "gid": "...",
        "layer": "venue",
        "source": "openstreetmap",
        "name": "White House",
        "confidence": 0.9,
        "distance": 0.0,
        "accuracy": "point"
      }
    }
  ],
  "bbox": [-77.0365, 38.8977, -77.0365, 38.8977]
}
```

### Error Handling
- **ApiException** - Thrown when the API call fails. Check the exception message for details.
```

--------------------------------

### Python example for AddressComponentsV2

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/AddressComponentsV2.md

Shows how to create an AddressComponentsV2 instance from a JSON string, convert it to a dict, and back. The JSON string is a placeholder that should be updated.

```python
from stadiamaps.models.address_components_v2 import AddressComponentsV2

# TODO update the JSON string below
json = "{}"
# create an instance of AddressComponentsV2 from a JSON string
address_components_v2_instance = AddressComponentsV2.from_json(json)
# print the JSON string representation of the object
print(AddressComponentsV2.to_json())

# convert the object into a dict
address_components_v2_dict = address_components_v2_instance.to_dict()
# create an instance of AddressComponentsV2 from a dict
address_components_v2_from_dict = AddressComponentsV2.from_dict(address_components_v2_dict)
```

--------------------------------

### GET /geocoding/v1/search

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Documentation for the forward geocoding search endpoint of the GeocodingApi class.

```APIDOC
## [GET] /geocoding/v1/search

### Description
Performs a forward geocoding search to find places and addresses based on a free-form address string or structured address components. This endpoint is part of the GeocodingApi class in the stadiamaps Python client.

### Method
GET

### Endpoint
/geocoding/v1/search

### Parameters
#### Query Parameters
- **address** (str) - Optional - A street name and optional house number together, e.g. `11 Wall St`. If you have the data available separately, you should provide the house number and street separately.
- **house_number** (str) - Optional - A house or building number. Mutually exclusive with the `address` field. Requires `street` to also be specified.
- **street** (str) - Optional - A street name. Mutually exclusive with the `address` field.
- **unit** (str) - Optional - The apartment, suite, or unit number. Requires both `house_number` and `street` to be specified. Mutually exclusive with the `address` field.
- **neighbourhood** (str) - Optional - A smaller area within a locality, e.g. `Financial District`. Practices vary by area, but these are typically not distinct administrative units.
- **borough** (str) - Optional - A unit within a city, e.g. `Manhattan` (not widely used outside mega cities like NYC and Mexico City).
- **locality** (str) - Optional - The city, village, town, etc. that the place/address is part of.
- **county** (str) - Optional - Administrative divisions between localities and regions. Not commonly used as input to structured geocoding.
- **region** (str) - Optional - Typically the first administrative division within a country. For example, a US state or a Canadian province.
- **postalcode** (str) - Optional - A mail sorting code (e.g. a US ZIP code).
- **country** (str) - Optional - A country code in ISO 3116-1 alpha-2 or alpha-3 format.
- **focus_point_lat** (float) - Optional - The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`.
- **focus_point_lon** (float) - Optional - The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`.
- **boundary_rect_min_lat** (float) - Optional - Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary_rect_max_lat** (float) - Optional - Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary_rect_min_lon** (float) - Optional - Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary_rect_max_lon** (float) - Optional - Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified.
- **boundary_circle_lat** (float) - Optional - The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`.
- **boundary_circle_lon** (float) - Optional - The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`.
- **boundary_circle_radius** (float) - Optional - The radius of the circle (in kilometers) to limit the search to. Defaults to 50km (search) or 1km (reverse) if unspecified.
- **boundary_country** (List[str]) - Optional - A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format.
- **boundary_gid** (str) - Optional - The GID of an area to limit the search to.
- **layers** (List[GeocodingLayer]) - Optional - A list of layers to limit the search to.
- **sources** (List[GeocodingSource]) - Optional - A list of sources to limit the search to.
- **size** (int) - Optional - The maximum number of results to return.
- **lang** (str) - Optional - A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English.

### Request Example
```python
import stadiamaps

configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com",
    api_key = "YOUR_API_KEY"
)

with stadiamaps.ApiClient(configuration) as api_client:
    api_instance = stadiamaps.GeocodingApi(api_client)
    address = '11 Wall St'
    locality = 'New York'
    region = 'New York'
    postalcode = '10005'
    country = 'USA'
    size = 10
    api_response = api_instance.geocoding_search(
        address=address,
        locality=locality,
        region=region,
        postalcode=postalcode,
        country=country,
        size=size
    )
    print(api_response)
```

### Response
#### Success Response (200)
The response will contain a list of geocoding results. The exact structure is not detailed in the provided source.

#### Response Example
Not provided in the source.
```

--------------------------------

### place_details example with ApiKeyAuth

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Shows how to call place_details with API key authentication. Requires an API key set in the API_KEY environment variable. The response is printed using pprint.

```python
import stadiamaps
from stadiamaps.models.geocode_response import GeocodeResponse
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)
    ids = ['ids_example'] # List[str] | A list of GIDs to search for.
    lang = 'lang_example' # str | A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English. (optional)

    try:
        # Retrieve details of a place using its GID.
        api_response = api_instance.place_details(ids, lang=lang)
        print("The response of GeocodingApi->place_details:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling GeocodingApi->place_details: %s\n" % e)
```

--------------------------------

### GET /geocoding/v2/reverse

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Find places and addresses near a location point (reverse geocoding).

```APIDOC
## GET /geocoding/v2/reverse

### Description
Find places and addresses near a location point (reverse geocoding).

### Method
GET

### Endpoint
/geocoding/v2/reverse
```

--------------------------------

### Python example for search_bulk with ApiKeyAuth

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Shows how to call search_bulk using the stadiamaps Python client. Configure the API key via environment variable API_KEY, optionally set a prefix, and handle exceptions. The endpoint returns a list of BulkSearchResponse objects.

```python
import stadiamaps
from stadiamaps.models.bulk_request import BulkRequest
from stadiamaps.models.bulk_search_response import BulkSearchResponse
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)
    bulk_request = [stadiamaps.BulkRequest()] # List[BulkRequest] |  (optional)

    try:
        # Quickly run a batch of geocoding queries against the search, structured search, or reverse endpoints.
        api_response = api_instance.search_bulk(bulk_request=bulk_request)
        print("The response of GeocodingApi->search_bulk:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling GeocodingApi->search_bulk: %s\n" % e)

```

--------------------------------

### Call place_details_v2 with ApiKeyAuth

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Example of calling the place_details_v2 endpoint with API key authentication. The host defaults to https://api.stadiamaps.com, and the API key is read from the environment variable API_KEY. The lang parameter is optional and defaults to no localization.

```python
import stadiamaps
from stadiamaps.models.geocode_response_envelope_properties_v2 import GeocodeResponseEnvelopePropertiesV2
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)
    ids = ['[\"whosonfirst:locality:102026327\"]'] # List[str] | 
    lang = 'lang_example' # str | A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically. (optional)

    try:
        # Retrieve detailed information about a place by its GID.
        api_response = api_instance.place_details_v2(ids, lang=lang)
        print("The response of GeocodingApi->place_details_v2:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling GeocodingApi->place_details_v2: %s\n" % e)
```

--------------------------------

### GET /geocoding/v2/search

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Documentation for the forward geocoding search endpoint, including parameters, response, and error handling.

```APIDOC
## [GET] /geocoding/v2/search

### Description
Performs a forward geocoding search for addresses, place names, etc. The search can be constrained by focus point, layers, sources, and various boundary types.

### Method
GET

### Endpoint
/geocoding/v2/search

### Parameters
#### Query Parameters
- **text** (str) - Required - The text to search for (the start of an address, place name, etc.).
- **focus_point_lat** (float) - Optional - The latitude of a focus point. If provided (along with longitude), the search results should be more locally relevant.
- **focus_point_lon** (float) - Optional - The longitude of a focus point. If provided (along with longitude), the search results should be more locally relevant.
- **layers** (List[LayerId]) - Optional - A list of layers to limit the search to.
- **sources** (List[SourceId]) - Optional - A list of sources to limit the search to.
- **boundary_gid** (str) - Optional - The GID of a region to limit the search to. Note: these are not stable for all datasets! For example, OSM features may be deleted and re-added with a new ID.
- **boundary_country** (List[str]) - Optional - A list of comma-separated country codes in ISO 3116-1 alpha-2 or alpha-3 format. The search will be limited to these countries.
- **boundary_rect_min_lat** (float) - Optional - The minimum latitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_min_lon** (float) - Optional - The minimum longitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_max_lat** (float) - Optional - The maximum latitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_rect_max_lon** (float) - Optional - The maximum longitude component of a search bounding box. NOTE: Requires all other boundary.rect parameters to be specified.
- **boundary_circle_lat** (float) - Optional - The latitude of the center of a circle to limit the search to. NOTE: Requires boundary.circle.lon.
- **boundary_circle_lon** (float) - Optional - The longitude of the center of a circle to limit the search to. NOTE: Requires boundary.circle.lat.
- **boundary_circle_radius** (int) - Optional - The radius of the circle (in kilometers) to limit the search to. NOTE: Requires the other boundary.circle parameters to take effect. Defaults to 50km if unspecified.
- **size** (int) - Optional - The maximum number of items to return from a query.
- **lang** (str) - Optional - A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically.

### Response
#### Success Response (200)
- **GeocodeResponseEnvelopePropertiesV2** - A GeoJSON FeatureCollection with the results.

#### Error Responses
- **400** - A response with a description of why the request is malformed.
- **500** - A response with a description of what went wrong internally.

### Authorization
ApiKeyAuth

### HTTP Request Headers
- **Content-Type**: Not defined
- **Accept**: application/json
```

--------------------------------

### Geocoding API autocomplete_v2 with ApiKeyAuth

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Python example using the stadiamaps client to call the autocomplete_v2 endpoint. It configures the host to https://api.stadiamaps.com, sets the API key from the environment variable API_KEY, and demonstrates how to pass optional parameters like focus point, layers, sources, boundary filters, size, and lang. The response is printed using pprint.

```python
import stadiamaps
from stadiamaps.models.geocode_response_envelope_properties_v2 import GeocodeResponseEnvelopePropertiesV2
from stadiamaps.models.layer_id import LayerId
from stadiamaps.models.source_id import SourceId
from stadiamaps.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.stadiamaps.com
# See configuration.py for a list of all supported configuration parameters.
configuration = stadiamaps.Configuration(
    host = "https://api.stadiamaps.com"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: ApiKeyAuth
configuration.api_key['ApiKeyAuth'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['ApiKeyAuth'] = 'Bearer'

# Enter a context with an instance of the API client
with stadiamaps.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = stadiamaps.GeocodingApi(api_client)
    text = '1600 Pennsylvania Ave NW' # str | The text to search for (the start of an address, place name, etc.).
    focus_point_lat = 3.4 # float | The latitude of a focus point.  If provided (along with longitude), the search results should be more locally relevant. (optional)
    focus_point_lon = 3.4 # float | The longitude of a focus point.  If provided (along with longitude), the search results should be more locally relevant. (optional)
    layers = [stadiamaps.LayerId()] # List[LayerId] | A list of layers to limit the search to. (optional)
    sources = [stadiamaps.SourceId()] # List[SourceId] | A list of sources to limit the search to. (optional)
    boundary_gid = 'boundary_gid_example' # str | The GID of a region to limit the search to.  Note: these are not stable for all datasets! For example, OSM features may be deleted and re-added with a new ID. (optional)
    boundary_country = ['boundary_country_example'] # List[str] | A list of comma-separated country codes in ISO 3116-1 alpha-2 or alpha-3 format. The search will be limited to these countries. (optional)
    boundary_rect_min_lat = 3.4 # float | The minimum latitude component of a search bounding box.  NOTE: Requires all other boundary.rect parameters to be specified. (optional)
    boundary_rect_min_lon = 3.4 # float | The minimum longitude component of a search bounding box.  NOTE: Requires all other boundary.rect parameters to be specified. (optional)
    boundary_rect_max_lat = 3.4 # float | The maximum latitude component of a search bounding box.  NOTE: Requires all other boundary.rect parameters to be specified. (optional)
    boundary_rect_max_lon = 3.4 # float | The maximum longitude component of a search bounding box.  NOTE: Requires all other boundary.rect parameters to be specified. (optional)
    boundary_circle_lat = 3.4 # float | The latitude of the center of a circle to limit the search to.  NOTE: Requires boundary.circle.lon. (optional)
    boundary_circle_lon = 3.4 # float | The longitude of the center of a circle to limit the search to.  NOTE: Requires boundary.circle.lat. (optional)
    boundary_circle_radius = 56 # int | The radius of the circle (in kilometers) to limit the search to.  NOTE: Requires the other boundary.circle parameters to take effect. Defaults to 50km if unspecified. (optional)
    size = 56 # int | The maximum number of items to return from a query. (optional)
    lang = 'lang_example' # str | A BCP47 language tag which specifies a preference for localization of results. There is no default value, so place names will be returned as-is, which is usually in the local language. NOTE: The Accept-Language header is also respected, and many user agents will set it automatically. (optional)

    try:
        # Search and geocode quickly based on partial input.
        api_response = api_instance.autocomplete_v2(text, focus_point_lat=focus_point_lat, focus_point_lon=focus_point_lon, layers=layers, sources=sources, boundary_gid=boundary_gid, boundary_country=boundary_country, boundary_rect_min_lat=boundary_rect_min_lat, boundary_rect_min_lon=boundary_rect_min_lon, boundary_rect_max_lat=boundary_rect_max_lat, boundary_rect_max_lon=boundary_rect_max_lon, boundary_circle_lat=boundary_circle_lat, boundary_circle_lon=boundary_circle_lon, boundary_circle_radius=boundary_circle_radius, size=size, lang=lang)
        print("The response of GeocodingApi->autocomplete_v2:\n")
        pprint(api_response)
    except Exception as e:
        print("Exception when calling GeocodingApi->autocomplete_v2: %s\n" % e)
```

--------------------------------

### GET /geocoding/v2/search

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/docs/GeocodingApi.md

Search for location and other info using a place name or address (forward geocoding).

```APIDOC
## GET /geocoding/v2/search

### Description
Search for location and other info using a place name or address (forward geocoding).

### Method
GET

### Endpoint
/geocoding/v2/search
```

--------------------------------

### Install stadiamaps with poetry

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/README.md

Install the package using poetry.

```shell
poetry add stadiamaps
```

--------------------------------

### Install stadiamaps with pip

Source: https://github.com/stadiamaps/stadiamaps-api-py/blob/main/README.md

Install the package using pip.

```shell
pip install stadiamaps
```
Tokens:
Raw