Geocode and search Functions

Functions
SDK_ERROR SDK_API	SDK_SearchTown (const SDK_SearchRequest *pSearchRequest, SDK_INT4 MaxSearchResult, SDK_UINT4 *pSearchRequestIndex, SDK_INT4 *pFoundSearchResult, SDK_BOOL bOneEntryPerTown, SDK_ProgressCBFuncT pCallBackFunc)
SDK_ERROR SDK_API	SDK_SearchPostcode (const SDK_SearchRequest *pSearchRequest, SDK_INT4 MaxSearchResult, SDK_UINT4 *pSearchRequestIndex, SDK_INT4 *pFoundSearchResult, SDK_BOOL bMajorOnly, SDK_BOOL bOneEntryPerTown, SDK_INT4 DistinctHouseNumber, SDK_BOOL *pIsAmbiguous, SDK_ProgressCBFuncT pCallBackFunc)
SDK_ERROR SDK_API	SDK_SearchStreet (const SDK_SearchRequest *pSearchRequest, SDK_INT4 MaxSearchResult, SDK_UINT4 *pSearchRequestIndex, const SDK_SearchResult *pTownDescription, SDK_INT4 *pFoundSearchResult, SDK_ProgressCBFuncT pCallBackFunc)
SDK_ERROR SDK_API	SDK_SearchHouseNr (const SDK_SearchRequest *pSearchRequest, SDK_INT4 MaxSearchResult, SDK_UINT4 *pSearchRequestIndex, const SDK_SearchResult *pTownDescription, const SDK_SearchResult *pStreetDescription, SDK_INT4 *pFoundSearchResult, SDK_ProgressCBFuncT pCallBackFunc)
SDK_ERROR SDK_API	SDK_SearchCrossing (const SDK_SearchRequest *pSearchRequest, SDK_INT4 MaxSearchResult, SDK_UINT4 *pSearchRequestIndex, const SDK_SearchResult *pStreetDescription, SDK_INT4 *pFoundSearchResult, SDK_ProgressCBFuncT pCallBackFunc)
SDK_ERROR SDK_API	SDK_GetResult (SDK_UINT4 SearchRequestIndex, SDK_UINT4 SearchResultIndex, SDK_SearchResult *pSearchResult, SDK_BOOL generalizePLZ)
SDK_ERROR SDK_API	SDK_GetResultCount (SDK_UINT4 SearchRequestIndex, SDK_INT4 *pCount)
SDK_ERROR SDK_API	SDK_DestroySearchResult (SDK_UINT4 SearchRequestIndex)
SDK_ERROR SDK_API	SDK_ParseTownName (const SDK_WCHAR_T *pTownResultName, SDK_WCHAR_T **ppTownName, SDK_WCHAR_T **ppPostCode)
SDK_ERROR SDK_API	SDK_GeoCode (const SDK_Address *pSearchAddress, SDK_UINT4 *pRequestIndex)
SDK_ERROR SDK_API	SDK_InverseGeoCode (const SDK_Position *pPosition, SDK_UINT4 *pRequestIndex)
SDK_ERROR SDK_API	SDK_GetGeoCodeResult (const SDK_UINT4 requestIndex, SDK_Address *pResultAddress, SDK_Position *pPosition, SDK_UINT4 resultIndex)
SDK_ERROR SDK_API	SDK_DestroyGeoCodeResult (const SDK_UINT4 requestIndex)
SDK_ERROR SDK_API	SDK_MatchRoad (const SDK_Waypoint *pWaypoint, SDK_RoadMatchInformation *pRoadMatchInformation)

Detailed Description

Functions for searching addresses and geocoding.

Function Documentation

SDK_ERROR SDK_API SDK_SearchTown	(	const SDK_SearchRequest *	pSearchRequest,
		SDK_INT4	MaxSearchResult,
		SDK_UINT4 *	pSearchRequestIndex,
		SDK_INT4 *	pFoundSearchResult,
		SDK_BOOL	bOneEntryPerTown,
		SDK_ProgressCBFuncT	pCallBackFunc
	)

Search for a town.

Searches for a town depending on the name.

The search map is determined by the country code in the SDK_SearchRequest struct. The search function is independent of the current set map and there is no need to switch the map manually to the search map. The current map will not be switched by using this function. If the country code is set to "0", the current map will be used for the search. If the country code is not found, the function returns an error.

The result is not delivered, but an index to the result. To get the actual result, you have to use SDK_GetResult() with the returned index. The memory allocated by the API has to be freed by calling SDK_DestroySearchResult() with the approriate index.

Parameters

[in]	pSearchRequest	SearchRequest that contains the information to search for.
[in]	MaxSearchResult	Number of the maximum returned results.
[out]	pSearchRequestIndex	Index of the search result, use SDK_GetResult() to retrieve a particular result row.
[out]	pFoundSearchResult	Will be set to the number of found results.
[in]	bOneEntryPerTown	Only one entry per town will be returned. If set to SDK_FALSE, also districts of a town will be shown.
[in]	pCallBackFunc	Optional pointer to a callback function May be NULL or of type SDK_ProgressCBFuncT.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_SearchPostcode	(	const SDK_SearchRequest *	pSearchRequest,
		SDK_INT4	MaxSearchResult,
		SDK_UINT4 *	pSearchRequestIndex,
		SDK_INT4 *	pFoundSearchResult,
		SDK_BOOL	bMajorOnly,
		SDK_BOOL	bOneEntryPerTown,
		SDK_INT4	DistinctHouseNumber,
		SDK_BOOL *	pIsAmbiguous,
		SDK_ProgressCBFuncT	pCallBackFunc
	)

Searches for a postcode.

Searches for a town depending on the postcode.

The search map is determined by the country code in the SDK_SearchRequest struct. The search function is independent of the current set map and there is no need to switch the map manually to the search map. The current map will not be switched by using this function. If the country code is set to "0", the current map will be used for the search. If the country code is not found, the function returns an error.

The UK and the Netherlands have special postcode systems which are more complex. Searching one of these special postcodes is done by setting the search kind to SDK_SK_NL6POSTCODE or SDK_SK_UK7POSTCODE. This will trigger a search in special indexes. The UK7 index search will only be started when the request string has a minimum of 3 chars (to optimise search performance). If the request is shorter, an error will be returned. These two search kinds are only valid if the corresponding map is available. If not, an error will be returned. If searching in a UK or NL map with the standard search kind, the search will not take place in the special indexes and may be more inaccurate.

The result is not delivered, but an index to the result. To get the actual result, you have to use SDK_GetResult() with the returned index. The memory allocated by the API has to be freed by calling SDK_DestroySearchResult() with the approriate index.

Parameters

[in]	pSearchRequest	SearchRequest that contains the information to search for. Valid parameters are: SDK_SK_TOWNBYPOSTCODE for standard postcode search in all countries, SDK_SK_NL6POSTCODE for 6 digit postcode search in NL and SDK_SK_UK7POSTCODE for 7 digit postcode search in the UK (search request must have a minimum of 3 chars, otherwise an error will be returned).
[in]	MaxSearchResult	Number of the maximum returned results.
[out]	pSearchRequestIndex	Index of the search result, use SDK_GetResult() to retrieve a particular result row.
[out]	pFoundSearchResult	Will be set to the number of found results.
[in]	bMajorOnly	Only major cities are considered. Only used in standard postcode search (SearchKind == SDK_SK_TOWNBYPOSTCODE)
[in]	bOneEntryPerTown	Only one entry per town is found. Only used in standard postcode search (SearchKind == SDK_SK_TOWNBYPOSTCODE)
[in]	DistinctHouseNumber	Housenumber to get an exacter match of the results, if set to -1, all results fot the given postcode will be returned. Only used for NL6 postcodes (SearchKind == SDK_SK_NL6POSTCODE), standard postcode searches will ignore the number.
[out]	pIsAmbiguous	Set to SDK_TRUE, if result is ambiguous, Only used for NL6 postcodes (SearchKind == SDK_SK_NL6POSTCODE).
[in]	pCallBackFunc	Optional pointer to a callback function. May be NULL or of type SDK_ProgressCBFuncT.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_SearchStreet	(	const SDK_SearchRequest *	pSearchRequest,
		SDK_INT4	MaxSearchResult,
		SDK_UINT4 *	pSearchRequestIndex,
		const SDK_SearchResult *	pTownDescription,
		SDK_INT4 *	pFoundSearchResult,
		SDK_ProgressCBFuncT	pCallBackFunc
	)

Searches for a street.

Searches for a street depending on the name. A former SearchResult specifying a town must be available.

The result is not delivered, but an index to the result. To get the actual result, you have to use SDK_GetResult() with the returned index. The memory allocated by the API has to be freed by calling SDK_DestroySearchResult() with the approriate index.

Parameters

[in]	pSearchRequest	SearchRequest that contains the information to search for. By specifying SDK_SearchRequest.request=L"*" one may search for all streets within a town.
[in]	MaxSearchResult	Number of the maximum returned results.
[out]	pSearchRequestIndex	Index of the search result, use SDK_GetResult() to retrieve a particular result row.
[in]	pTownDescription	Existing SearchResult with town to search in.
[out]	pFoundSearchResult	Will be set to the number of found results.
[in]	pCallBackFunc	Optional pointer to a callback function. May be NULL or of type SDK_ProgressCBFuncT.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_SearchHouseNr	(	const SDK_SearchRequest *	pSearchRequest,
		SDK_INT4	MaxSearchResult,
		SDK_UINT4 *	pSearchRequestIndex,
		const SDK_SearchResult *	pTownDescription,
		const SDK_SearchResult *	pStreetDescription,
		SDK_INT4 *	pFoundSearchResult,
		SDK_ProgressCBFuncT	pCallBackFunc
	)

Search for a house number.

Searches for a house number. A former SearchResult specifying a street must be available.

The result is not delivered, but an index to the result. To get the actual result, you have to use SDK_GetResult() with the returned index. The memory allocated by the API has to be freed by calling SDK_DestroySearchResult() with the approriate index.

Parameters

[in]	pSearchRequest	SearchRequest that contains the information to search for.
[in]	MaxSearchResult	Number of the maximum returned results.
[out]	pSearchRequestIndex	Index of the search result, use SDK_GetResult() to retrieve a particular result row. So far only single house numbers may be searched. If the result however contains a range as indicated by the name (string) the result is an explicit extrapolation of existing data. E.g. the search for the house number "11" may have the result string "3-11" to indicate that the closest match (numerically!) within the data was house number "3", there is no dataset for "11". The result has to be cleaned up by calling SDK_DestroySearchResult(),
[in]	pTownDescription	Existing SearchResult with town to search in.
[in]	pStreetDescription	Existing SearchResult with street to search in.
[out]	pFoundSearchResult	Number of found results.
[in]	pCallBackFunc	Optional pointer to a callback function. May be NULL or of type SDK_ProgressCBFuncT.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_SearchCrossing	(	const SDK_SearchRequest *	pSearchRequest,
		SDK_INT4	MaxSearchResult,
		SDK_UINT4 *	pSearchRequestIndex,
		const SDK_SearchResult *	pStreetDescription,
		SDK_INT4 *	pFoundSearchResult,
		SDK_ProgressCBFuncT	pCallBackFunc
	)

Search for all intersections of the given street.

Search for all intersections of the given street. The result is not delivered, but an index to the result. To get the actual result, you have to use SDK_GetResult() with the returned index. The memory allocated by the API has to be freed by calling SDK_DestroySearchResult() with the approriate index.

Parameters

[in]	pSearchRequest	SearchRequest that contains the information to search for.
[in]	MaxSearchResult	Number of the maximum returned results.
[out]	pSearchRequestIndex	Index of the search result, use SDK_GetResult() to retrieve a particular result row.
[in]	pStreetDescription	Former or new SearchResult with town and street to search in.
[out]	pFoundSearchResult	Number of found results.
[in]	pCallBackFunc	Optional pointer to a callback function. May be NULL or of type SDK_ProgressCBFuncT.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_GetResult	(	SDK_UINT4	SearchRequestIndex,
		SDK_UINT4	SearchResultIndex,
		SDK_SearchResult *	pSearchResult,
		SDK_BOOL	generalizePLZ
	)

Retrieve a particular result row.

Retrieve a particular search result row from a search given by searchRequestIndex.

Parameters

[in]	SearchRequestIndex	Index of the search result.
[in]	SearchResultIndex	Row index of the wanted result.
[out]	pSearchResult	The referenced address will be set to pointer to the matching result.
[in]	generalizePLZ	Flag whether the post code should be generalized and the name should be preprocessed by SDK_ParseTownName(). Only used for town searches. Generalization means that the last 1 to 3 digits of the postcode will be replaced with dots dependent on the category of the town. Towns with cat 1 get the last 3 digits replaced, towns with cat 2 get the last 2 digits replaced and finally towns with cat 3 get 1 digit replaced. Also, the town name will be preprocessed automatically with the functionality given in SDK_ParseTownName(). "Karlsruhe[76131]" with category 3 will be returned as "D 7613. Karlsruhe" and "Berlin[10115]" with category 1 will be returned as "D 10... Berlin"

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_GetResultCount	(	SDK_UINT4	SearchRequestIndex,
		SDK_INT4 *	pCount
	)

Get the result count for a particular search result identified by searchRequestIndex.

Parameters

[in]	SearchRequestIndex	Index of the search.
[out]	Count	The number of search results in the search given by searchRequestIndex.

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_DestroySearchResult

(

SDK_UINT4

SearchRequestIndex

)

Free memory for search results.

Parameters

[in]

SearchRequestIndex

Index of the search which should be cleared

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_ParseTownName	(	const SDK_WCHAR_T *	pTownResultName,
		SDK_WCHAR_T **	ppTownName,
		SDK_WCHAR_T **	ppPostCode
	)

Parse a town name returned by a search.

Parameters

[in]	pTownResultName	Pointer to town name as returned from a suitable interface, e.g. SearchTown. That's the value found in the name filed of a SDK_SearchResult
[out]	ppTownName	Pointer which will be set to the string representing the town name. The result may still contain combined major and minor entries like "Capital/Suburb" May be NULL! If non-NULL the returned buffer has to be freed by calling SDK_FreeString()
[out]	ppPostCode	Pointer which will be set to the string representing the postcode. May be NULL! If non-NULL the returned buffer has to be freed by calling SDK_FreeString()

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_GeoCode	(	const SDK_Address *	pSearchAddress,
		SDK_UINT4 *	pRequestIndex
	)

Do a simple geocoding.

Fill a SDK_Address object with the address information. The function geocodes the given address and return the result in the ResultAddress object. pResultPosition stores the coordinates of the geocoded address (Mercator format).

The search map is determined by the country code in the SDK_Address struct field "Cc". The search function is independent of the current set map and there is no need to switch the map manually to the search map. The current map will not be switched by using this function. If the country code is set to "0", the current map will be used for the search. If the country code is not found, the function returns an error.

Parameters

[in]	pSearchAddress	Pointer to SDK_Address to search for.
[out]	pRequestIndex	Will be set to the index of the search request. You can get the actual result with SDK_GetGeoCodeResult() Memory has to be released by calling SDK_DestroyGeoCodeResult()

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_InverseGeoCode	(	const SDK_Position *	pPosition,
		SDK_UINT4 *	pRequestIndex
	)

Does inverse geocoding.

Inverse geocoding returns a postal address to a given coordinate.

The search map is determined automatically by the position. The search function is independent of the current set map and there is no need to switch the map manually to the search map. The current map will not be switched by using this function.

The housenumber field of the filled ppResultAddress object contains a range of housenumbers for each side of the found street part.

Note that there is not always a precise or even unique result. Also note that this may be a very time-consuming task because a lot of data has to be looked up for inverse references.

Parameters

[in]	pPosition	Pointer to the position (Mercator coordinate) to be geocoded
[out]	pRequestIndex	Will be set to the index of the search request. You can get the actual result with SDK_GetGeoCodeResult() Memory has to be released by calling SDK_DestroyGeoCodeResult()

Returns

Error code (Errorcodes). If SDK_ERROR_OutOfTown the town specified is only an arbitrary town nearby, usually the closest match, but the street does not belong to that town and its street table

SDK_ERROR SDK_API SDK_GetGeoCodeResult	(	const SDK_UINT4	requestIndex,
		SDK_Address *	pResultAddress,
		SDK_Position *	pPosition,
		SDK_UINT4	resultIndex
	)

Get the result of SDK_InverseGeoCode() or SDK_GeoCode()

Parameters

[out]	pResultAddress	will be set to the matched adress
[out]	pPosition	will be set to the matched position
	resultIndex	currently unused

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_DestroyGeoCodeResult

(

const SDK_UINT4

requestIndex

)

Releases memory for geocoding results.

Parameters

[in]

requestIndex

index of the search results

Returns

Error code (Errorcodes)

SDK_ERROR SDK_API SDK_MatchRoad	(	const SDK_Waypoint *	pWaypoint,
		SDK_RoadMatchInformation *	pRoadMatchInformation
	)

Perform information about the current position on a road (does not require navigation context!)

This interface may be used to perform a roadmatch for the given position data. The course is considered for matching as SDK_INT4 as it is not -1.

Parameters

[in]	*pWaypoint	The position data to roadmatch. If this pointer is NULL, road match uses the last result of getGuidanceInformation() to fill the data structure pRoadMatchInformation.
[out]	pRoadMatchInformation	This data structure stores the information that is returned by this interface

Returns

Error code (Errorcodes)