Classes¶
This section describes the usage of Geo Addressing SDK Classes and APIs:
AddressingBuilder¶
-
class
addressing.AddressingBuilder.AddressingBuilder¶ This builder class allows you to create a UDF that executes an addressing operation.
-
addressingProvider()¶ A serializable provider for the Addressing API, configured with the builder settings, that can be shared among tasks.
- Returns
A serializable Addressing API provider.
- Return type
-
udfBuilder()¶ A builder for an addressing UDF, configured with the current Addressing API settings from this builder.
- Returns
An object of UDFBuilder Class
- Return type
-
withDataLocations(*dataLocations)¶ Add locations to addressing datasets. If the location is a remote path, e.g. HDFS or S3, then a suitable download manager instance must also be provided to the builder (see
withDownloadManager()). A dataLocation may be a single dataset (extracted or an unextracted SPD), or a location with multiple datasets. Local paths must be present on all nodes that tasks will run on.- Parameters
dataLocations (list[str] or str) – The data locations for the reference data.
- Returns
An object of AddressingBuilder class
- Return type
-
withDownloadManager(downloadManager)¶ Add a configured download manager to use when downloading from remote paths. If multiple download managers claim to support a path, then the download manager added first will be used.
- Parameters
downloadManager (S3Downloader or HDFSDownloader or LocalFilePassthroughDownloader) – The download manager configured for required remote locations.
- Returns
An object of AddressingBuilder class
- Return type
-
withExtractionLocation(extractionLocation)¶ Specify an alternate extraction location for addressing datasets. Default location is the alongside the SPD.
- Parameters
extractionLocation (str) – The local path where the data needs to be extracted
- Returns
An object of AddressingBuilder class
- Return type
-
withResourcesLocation(resourcesLocation)¶ Sets the resources location for the Addressing API. If the location is a remote path, e.g. HDFS or S3, then a suitable download manager instance must also be provided to the builder (see
withDownloadManager()). If a local path is supplied, then it must be accessible on all nodes that tasks will run on.- Parameters
resourceLocation (str) – The resources location for the Addressing API.
- Returns
An object of AddressingBuilder class.
- Return type
-
UDFBuilder¶
-
class
addressing.UDFBuilder.UDFBuilder(AddressingBuilder)¶ This class allows you to build a UDF that executes an addressing operation. You can obtain an instance of this builder by starting with an
addressing.AddressingBuilder.AddressingBuilder-
forGeocode()¶ Build a UDF to geocode an address, based on the provided configuration options. This UDF has a single argument that is a map of String to Column. The String keys are the address fields that are to be populated in the RequestAddress, and the column is the value to populate the fields with.
- Returns
A UDF that executes the geocode operation of the Addressing API.
- Return type
-
forLookup()¶ Build a UDF to lookup a geocoded candidates when given a unique key, based on the provided configuration options. This UDF takes two arguments, lookupType Key type- it can be GNAF_PID or PB_KEY, Key to search and country.
- Returns
A UDF that provides a lookup operation.
- Return type
-
forReverseGeocode()¶ Build a UDF to reverse geocode a location, based on the provided configuration options. This UDF takes X and Y coordinates of location to reverse geocode with optional country parameter.
- Returns
A UDF that executes the reverse geocode operation of the Addressing API.
- Return type
-
forVerify()¶ Build a UDF to verify an address, based on the provided configuration options. This UDF has a single argument that is a map of String to Column. The String keys are the address fields that are to be populated in the RequestAddress, and the column is the value to populate the fields with.
- Returns
A UDF that provides a verify operation.
- Return type
-
withErrorField(errorOutputFieldName)¶ Adds an output field for errors. Exceptions during processing of a record are caught and then the message is placed in this output field.
- Parameters
errorOutputFieldName (str) – The name for the field in the output that any error message is placed.
- Returns
An object of UDFBuilder class
- Return type
-
withMultipleResults()¶ Changes the output of the UDF from a single row of output fields, taken from the top candidate, to an array of rows of output fields, one for each result in the response.
- Note
In order to get back multiple results, preferences must be set to allow that.
- Returns
An object of UDFBuilder class
- Return type
-
withOutputFields(*fieldNames)¶ Adds output fields for the UDF. Allows you to access any part of the Addressing API Result class. You can use a simple object notation to access sub objects:
- Accessing Properties:
Use property name, case of first letter is flexible, i.e. “score” would return the value in Result.score
Accessing nested properties can be done using a period, i.e. “address.formattedAddress” would return the value in Result.address.formattedAddress
- Accessing Lists and Arrays:
Use square brackets and string literal values, i.e. “parsed[‘ggs’]” would return the value associated with ‘ggs’ in the Result.parsed map
While evaluating the object notation any nulls encountered along the path will cause a null value to be returned. A property that isn’t found will result in an error.
- The output field notation also allows aliasing:
You can use a simple ‘as’ syntax with an alpha numeric alias, i.e. “address.formattedAddress as address” would have an output field name of ‘address’
If you need special characters in the output field name you can use a quoted literal for the alias, i.e. “address.formattedAddress as ‘formatted_address’” would have an output field name of ‘formatted_address’
- Parameters
fieldNames (list[str] or str) – The object notation access field names, which will also be the UDF output field names.
- Returns
An object of UDFBuilder class
- Return type
-
withPreferences(preferences)¶ Sets the preferences that will be used for all geocode calls.
- Parameters
preferences (
Preferences) – A preferences instance- Returns
An object of UDFBuilder class
- Return type
-
withPreferencesFile(file)¶ Sets the location of a yaml configuration file with the desired preferences. Any specific preferences set in this yaml will override the preferences provided by
withPreferences()- Parameters
file (str) – The location of a yaml configuration file.
- Returns
An object of UDFBuilder class
- Return type
-
withResultAsJSON(jsonOutputFieldName)¶ Adds an output field for Json response. Exceptions during processing of a record are caught and then the message is placed in the error field.
- Parameters
jsonOutputFieldName (str) – The name for the field in the output where that json Response is placed.
- Returns
An object of UDFBuilder class
- Return type
-
DownloadManagerBuilder¶
-
class
addressing.DownloadManagerBuilder.DownloadManagerBuilder(downloadLocation=None, permissions=None)¶ This builder class to configure downloading from remote paths.
-
addDownloader(downloader)¶ Adds a configured download manager to use when downloading from remote paths. If multiple download managers claim to support a path, then the download manager added first will be used.
- Parameters
downloader – The downloader configuration for remote path.
- Returns
An object of DownloadManagerBuilder class
- Return type
-
build()¶ Returns the configured DownloadManager used when downloading from remote paths.
- Returns
An object of configured DownloadManager class
- Return type
-
PreferencesBuilder¶
-
class
addressing.PreferencesBuilder.PreferencesBuilder¶ This builder class is used to Configure the Preferences required for Addressing API.
-
build()¶ Builds and returns the preferences object
- Returns
An object of ImmutablePreferences class from Addressing SDK
- Return type
-
withClientCoordSysName(clientCoordSysName)¶ Configures the passed Co-ordinate System for the Addressing API
- Parameters
clientCoordSysName (str) – custom co-ordinate system
- Returns
An object of PreferenesBuilder class
- Return type
-
withClientLocale(locale)¶ Enables the configuration for Locale
- Parameters
locale (
Locale) – An object of Locale- Returns
An object of PreferenesBuilder class
- Return type
-
withCornerOffset(cornerOffset)¶ Configures the Offset for corner parameter in the Preferences
- Parameters
cornerOffset – An object of Distance containing the corner offset parameters
- Returns
An object of PreferenesBuilder class
- Return type
-
withCustomPreferences(key, value)¶ Sets the key and value as the Custom Preferences
- Parameters
key (str) – a key for the custom preference
value (str) – a value for the custom preference
- Returns
An object of PreferenesBuilder class
- Return type
-
withDistance(distance)¶ Sets the object of distance in the Preferences
- Parameters
distance (
Distance) – An object of Distance- Returns
An object of PreferenesBuilder class
- Return type
-
withFactoryDescription(description)¶ Configures the factory description information
- Parameters
description (
FactoryDescription) – An object of FactoryDescription- Returns
An object of PreferenesBuilder class
- Return type
-
withFallbackToGeographic(fallBackToGeographic)¶ An option for Geographic Fallback
- Parameters
fallBackToGeographic (bool) – flag to enable geographic fallback
- Returns
An object of PreferenesBuilder class
- Return type
-
withFallbackToPostal(fallbackToPostal)¶ An option for Postal Fallback
- Parameters
fallbackToPostal (bool) – flag to enable postal fallback
- Returns
An object of PreferenesBuilder class
- Return type
-
withMatchMode(originXY)¶ Confiugures the passed list of coordinates for match modes in the preferences
- Parameters
matchMode (list[float]) – a list of match modes
- Returns
An object of PreferenesBuilder class
- Return type
-
withMaxResults(maxResults)¶ Sets the Maximum Number of Results in the Addressing API output.
- Parameters
maxResults (int) – the number of required maximum results that addressing API should return
- Returns
An object of PreferenesBuilder class
- Return type
-
withReturnAllInfo(returnAllInfo)¶ Allows Addressing API to return all the information available like custom fields, etc.
- Parameters
returnAllInfo (bool) – flag to indicate whether to return the all info or not. Defaults to
false- Returns
An object of PreferenesBuilder class
- Return type
-
withReturnOfAdditionalFields(*returnAdditionalFields)¶ Configures the passed fields to return in the output of Addressing APIs
- Parameters
returnAdditionalFields (list[str] or str) – a list of additional fields to configure
- Returns
An object of PreferenesBuilder class
- Return type
-
UDFExecutor¶
-
class
addressing.UDFExecutor.UDFExecutor¶ This class is responsible for Executing the UDF Operations
S3Downloader¶
HDFSDownloader¶
-
class
addressing.HDFSDownloader.HDFSDownloader(hadoopConfiguration)¶ This Downloader class is used enabling the use of data located at HDFS.
-
getDownloader()¶ Returns the object reference of HDFS Downloader responsible for downloading the data from HDFS.
- Returns
An object of HDFSDownloader
- Return type
-
LocalFilePassthroughDownloader¶
-
class
addressing.LocalFilePassthroughDownloader.LocalFilePassthroughDownloader¶ This Downloader class is used enabling the use of data located at Local File System.
-
getDownloader()¶ Returns the object reference of Local Downloader responsible for downloading the data from Local File System.
- Returns
An object of LocalFilePassthroughDownloader
- Return type
-
