casageo.coder module

This module provides geocoding and search operations.

Address Queries

Geocode addresses.

You can supply either a free-form address string or a combination of country, state, county, city, district, street, house number and postal code. Combining these two approaches is also supported.

If the input data combines street and house number information into a single field, you can pass the resulting string to the street field and leave the housenumber field unset.

If you specify a position for the search, the search will favor places around that position and distance values will be computed for the results.

The structured address fields are not hard filters, meaning it is possible to receive results from outside the specified country or city. In contrast, the countries list is a hard filter, limiting the search to only the specified countries.

Address Query Options

address_detailsbool: Include additional address details in the result.
coordinatesbool: Include numeric coordinate columns in the result.
match_qualitybool: Include match quality scores in the result.

Address Input Columns

The following columns will be read from the input dataframe:

idAny

Fixed identifier to be added to each result of this query.

addressstr

A free-form address string.

countrystr

The name of a country.

statestr

The name of a state or province.

countystr

The name of a county.

citystr

The name of a city.

districtstr

The name of a city district.

streetstr

The name of a street, optionally including a house number.

housenumberstr

The house number, including any extensions.

postalcodestr

The postal code.

positionPoint

The geographical center of the search. Instead of a geometry object, you may also specify this as two separate fields position_latitude and position_longitude of type float.

languagestr

The preferred language for the response. This must be a valid IETF BCP47 language tag, such as "en-US", or a comma-separated list of such tags in order of preference.

political_viewstr

The political view of the query regarding disputed territories. This must be a valid ISO 3166-1 alpha-3 country code.

limitint

Limit on the number of results to return for each query. Must be between 1 and 100. If unset, the default limit will be used.

countriesstr | list[str]

If set, the search is limited to the specified countries. Must be a sequence of valid ISO 3166-1 alpha-3 country codes. This parameter treats a comma-separated string as a list of strings.

address_names_modestr

How to handle places with multiple names.

"default" – Prefer matched names for administrative places and normalized names for street names.
"matched" – Prefer names that match the input query.
"normalized" – Prefer the official names of places.

postal_code_modestr

How to handle postal codes spanning multiple cities or districts.

"default" – Return only one result per postal code, leaving the city or district name blank if necessary.
"cityLookup" – When a postal code spans multiple cities, return all possible combinations of the postal code with the corresponding city names.
"districtLookup" – When a postal code spans multiple districts, return all possible combinations of the postal code with the corresponding city and district names.

Address Output Columns

The resulting dataframe contains the following columns:

idAny: Fixed identifier added to each result of a query.
subidint: Numeric index of the result starting from zero.
addressstr: Localized display name of this result item.
resulttypestr: The type of the result item, one of "addressBlock", "administrativeArea", "houseNumber", "intersection", "locality", "place", "postalCodePoint" or "street".
positionPoint: The coordinates of a pin on a map corresponding to the item.
navigationPoint: The coordinates of a navigation point corresponding to the item.
distanceint: The distance from the search position to the result item in meters.
relevancefloat: The relevance of the result to the query as a number between zero and one.
timestampdatetime: Timestamp of when this result was created.

When address_details is True, the dataframe also contains the following columns:

postaladdressstr: Full address of the item, formatted according to the regional postal rules. May not include all address components.
countrystr: Name of the country.
countrycodestr: ISO 3166-1 alpha-3 country code of the country.
statestr: Name of the state within the country.
statecodestr: Code or abbreviation of the state.
countystr: Name of the county or subdivision within the state.
countycodestr: Code or abbreviation of the county.
citystr: Name of the city.
districtstr: Name of the district within the city.
subdistrictstr: Name of the subdistrict within the city.
streetstr: Name of the street.
streetslist[str]: List of street names on an intersection.
blockstr: Name of the city block.
subblockstr: Name of the subblock within the city block.
postalcodestr: Postal code associated with the item.
housenumberstr: House number, including associated qualifiers.
buildingstr: Name of the building.
unitstr: Information about the unit within the building.

When coordinates is True, the dataframe also contains the following columns:

position_longitudefloat: Longitude of the item’s position.
position_latitudefloat: Latitude of the item’s position.
navigation_longitudefloat: Longitude of the navigation point.
navigation_latitudefloat: Latitude of the navigation point.

When match_quality is True, the dataframe also contains the columns below. Each of the values is a number between zero and one, indicating how well the output field matches the corresponding input field.

mq_countryfloat: Match quality of the country field.
mq_countrycodefloat: Match quality of the countrycode field.
mq_statefloat: Match quality of the state field.
mq_statecodefloat: Match quality of the statecode field.
mq_countyfloat: Match quality of the county field.
mq_countycodefloat: Match quality of the countycode field.
mq_cityfloat: Match quality of the city field.
mq_districtfloat: Match quality of the district field.
mq_subdistrictfloat: Match quality of the subdistrict field.
mq_streetfloat: Average match quality of the streets field against each street name in the input query.
mq_blockfloat: Match quality of the block field.
mq_subblockfloat: Match quality of the subblock field.
mq_postalcodefloat: Match quality of the postalcode field.
mq_housenumberfloat: Match quality of the housenumber field. If the requested house number could not be found, this indicates the numeric difference between the requested house number and the returned house number.
mq_buildingfloat: Match quality of the building field.
mq_unitfloat: Match quality of the unit field.
mq_placenamefloat: Match quality of the resulting place name against the input query.
mq_ontologynamefloat: Match quality of the resulting ontology name against the input query.

Finally, the dataframe always contains the following error information columns. These contain values only if the corresponding query could not be executed for some reason.

error_codestr: String indicating the type of error.
error_messagestr: Human-readable error message.

POI Queries

Search for points of interest (POI) around given positions.

POI Query Options

address_detailsbool: Include additional address details in the result.
coordinatesbool: Include numeric coordinate columns in the result.
category_codesbool: Include HERE category, chain and food type identifiers in the result.

POI Input Columns

The following columns will be read from the input dataframe:

idAny

Fixed identifier to be added to each result of this query.

positionPoint

The geographical center of the search. Instead of a geometry object, you may also specify this as two separate fields position_latitude and position_longitude of type float.

languagestr

The preferred language for the response. This must be a valid IETF BCP47 language tag, such as "en-US", or a comma-separated list of such tags in order of preference.

political_viewstr

The political view of the query regarding disputed territories. This must be a valid ISO 3166-1 alpha-3 country code.

limitint

Limit on the number of results to return for each query. Must be between 1 and 100. If unset, the default limit will be used.

countriesstr | list[str]

If set, the search is limited to the specified countries. Must be a sequence of valid ISO 3166-1 alpha-3 country codes. This parameter treats a comma-separated string as a list of strings.

address_names_modestr

How to handle places with multiple names.

"default" – Prefer matched names for administrative places and normalized names for street names.
"matched" – Prefer names that match the input query.
"normalized" – Prefer the official names of places.

postal_code_modestr

How to handle postal codes spanning multiple cities or districts.

"default" – Return only one result per postal code, leaving the city or district name blank if necessary.
"cityLookup" – When a postal code spans multiple cities, return all possible combinations of the postal code with the corresponding city names.
"districtLookup" – When a postal code spans multiple districts, return all possible combinations of the postal code with the corresponding city and district names.

POI Output Columns

The resulting dataframe contains the following columns:

idAny: Fixed identifier added to each result of a query.
subidint: Numeric index of the result starting from zero.
titlestr: Localized display name of this result item.
resulttypestr: The type of the result item.
positionPoint: The coordinates of a pin on a map corresponding to the item.
navigationPoint: The coordinates of a navigation point corresponding to the item.
distanceint: The distance from the search position to the result item in meters.
timestampdatetime: Timestamp of when this result was created.

When address_details is True, the dataframe also contains the following columns:

postaladdressstr: Full address of the item, formatted according to the regional postal rules. May not include all address components.
countrystr: Name of the country.
countrycodestr: ISO 3166-1 alpha-3 country code of the country.
statestr: Name of the state within the country.
statecodestr: Code or abbreviation of the state.
countystr: Name of the county or subdivision within the state.
countycodestr: Code or abbreviation of the county.
citystr: Name of the city.
districtstr: Name of the district within the city.
subdistrictstr: Name of the subdistrict within the city.
streetstr: Name of the street.
streetslist[str]: List of street names on an intersection.
blockstr: Name of the city block.
subblockstr: Name of the subblock within the city block.
postalcodestr: Postal code associated with the item.
housenumberstr: House number, including associated qualifiers.
buildingstr: Name of the building.
unitstr: Information about the unit within the building.

When coordinates is True, the dataframe also contains the following columns:

position_longitudefloat: Longitude of the item’s position.
position_latitudefloat: Latitude of the item’s position.
navigation_longitudefloat: Longitude of the navigation point.
navigation_latitudefloat: Latitude of the navigation point.

When category_codes is True, the dataframe also contains the following columns:

here_categorieslist[str]: List of HERE category identifiers assigned to the item.
here_chainslist[str]: List of HERE chain identifiers assigned to the item.
here_foodtypeslist[str]: List of HERE food type identifiers assigned to the item.

Finally, the dataframe always contains the following error information columns. These contain values only if the corresponding query could not be executed for some reason.

error_codestr: String indicating the type of error.
error_messagestr: Human-readable error message.

casageo.coder.DEFAULT_LANGUAGE: str = 'en-US': The default language used in the results.

casageo.coder.DEFAULT_POLITICAL_VIEW: str | None = None: The default political view used in the results.

casageo.coder.DEFAULT_LIMIT: int = 20: The default limit on the number of computed results.

casageo.coder.DEFAULT_COUNTRIES: tuple[str, ...] | None = None: The default list of countries to restrict the search to.

casageo.coder.DEFAULT_ADDRESS_NAMES_MODE: str = 'default': The default address names mode.

casageo.coder.DEFAULT_POSTAL_CODE_MODE: str = 'default': The default postal code mode.

casageo.coder.address(client, queries, defaults=None, *, address_details=False, coordinates=False, match_quality=False)

Geocode addresses.

See Address Queries in the module documentation.

Parameters:

client (CasaGeoClient) – The client object authorizing these queries.
queries (DataFrame) – The dataframe of queries.
defaults (dict | None) – An optional dict of default values for missing input columns.
address_details (bool) – Include additional address details in the result.
coordinates (bool) – Include numeric coordinate columns in the result.
match_quality (bool) – Include match quality scores in the result.

Returns:

The list of results as an EPSG:4326 GeoDataFrame. The shape is described under Address Output Columns in the module documentation.

The geometry column of the dataframe is the position column. If you want to work with navigation points instead, change it to the navigation column instead.

Return type:

GeoDataFrame

Raises:

InsufficientCreditsError – If the account does not have enough credits.
CasaGeoError – If the request could not be executed for another reason.

casageo.coder.poi(client, queries, defaults=None, *, address_details=False, coordinates=False, category_codes=False)