Geocoder

---

This provides APIs for Geocoder Service.

The Maps Geocoding API allows translating an address to its geographical location defined in terms of latitude and longitude; the input can be a qualified, structured address or a free form single search text with full or partial address information.
The Maps Reverse Geocoding API allows to inverse translating a geographical location (longitude, latitude) to an address; it can be used to answer the question "Where am I?".

Functions
int	maps_service_geocode (const maps_service_h maps, const char *address, const maps_preference_h preference, maps_service_geocode_cb callback, void *user_data, int *request_id)
	Gets the position coordinates for a given address. The request is asynchronous.
int	maps_service_geocode_inside_area (const maps_service_h maps, const char *address, const maps_area_h bounds, const maps_preference_h preference, maps_service_geocode_cb callback, void *user_data, int *request_id)
	Gets the position for a given address within the specified bounding box. The request is asynchronous.
int	maps_service_geocode_by_structured_address (const maps_service_h maps, const maps_address_h address, const maps_preference_h preference, maps_service_geocode_cb callback, void *user_data, int *request_id)
	Gets the position coordinates for a given address. The request is asynchronous.
int	maps_service_reverse_geocode (const maps_service_h maps, double latitude, double longitude, const maps_preference_h preference, maps_service_reverse_geocode_cb callback, void *user_data, int *request_id)
	Gets the address for a given position coordinates. The request is asynchronous.
int	maps_service_multi_reverse_geocode (const maps_service_h maps, maps_coordinates_list_h coordinates_list, const maps_preference_h preference, maps_service_multi_reverse_geocode_cb callback, void *user_data, int *request_id)
	Gets the address list for a given position coordinates list. The request is asynchronous.
Typedefs
typedef bool(*	maps_service_geocode_cb )(maps_error_e result, int request_id, int index, int total, maps_coordinates_h coordinates, void *user_data)
	Called once for each position coordinates converted from the given address information.
typedef void(*	maps_service_reverse_geocode_cb )(maps_error_e result, int request_id, int index, int total, maps_address_h address, void *user_data)
	Called when the address information is converted from position information.
typedef bool(*	maps_service_multi_reverse_geocode_cb )(maps_error_e result, int request_id, int total, maps_address_list_h address_list, void *user_data)
	Called when respond to a request of multi reverse geocoding.

---

Typedef Documentation

typedef bool(* maps_service_geocode_cb)(maps_error_e result, int request_id, int index, int total, maps_coordinates_h coordinates, void *user_data)

Called once for each position coordinates converted from the given address information.

The Maps Service invokes this callback while iterating through the list of obtained coordinates of the specified place.
If search is failed, the value of total is 0 and coordinates is NULL.

Since :

2.4

Remarks:

The parameter coordinates must be released using maps_coordinates_destroy().
This error code will be reported.
MAPS_ERROR_NONE
MAPS_ERROR_OUT_OF_MEMORY
MAPS_ERROR_INVALID_PARAMETER
MAPS_ERROR_NOT_FOUND.

Parameters:

[in]	result	The result of request
[in]	request_id	The ID of request
[in]	index	The current index of coordinates in result set, start from 0
[in]	total	The total number of results
[in]	coordinates	The coordinates of the place
[in]	user_data	The user data passed from maps_service_geocode() or maps_service_geocode_inside_area()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_service_geocode() or maps_service_geocode_inside_area() will invoke this callback.

See also:

maps_service_geocode()

maps_service_geocode_inside_area()

maps_service_cancel_request()

typedef bool(* maps_service_multi_reverse_geocode_cb)(maps_error_e result, int request_id, int total, maps_address_list_h address_list, void *user_data)

Called when respond to a request of multi reverse geocoding.

The Maps Service invokes this callback once when gets the response from map service provider.
The value of total is same with requested coordinates list size. Even though one of address is not provided valid address handle is retrieved.

Since :

3.0

Remarks:

You can get the respective address information of address_list using maps_address_list_foreach().
This error code will be reported.
MAPS_ERROR_NONE
MAPS_ERROR_OUT_OF_MEMORY
MAPS_ERROR_INVALID_PARAMETER
MAPS_ERROR_NOT_FOUND.

Parameters:

[in]	result	The result of request
[in]	request_id	The ID of request
[in]	total	The total number of results
[in]	address_list	The converted address list from the requested coordinates list
[in]	user_data	The user data pointer passed from maps_service_multi_reverse_geocode()

Returns:

true to continue with the next iteration of the loop,
false to break out of the loop

Precondition:

maps_service_multi_reverse_geocode() will invoke this callback.

See also:

maps_service_multi_reverse_geocode()

maps_address_list_foreach()

maps_service_cancel_request()

typedef void(* maps_service_reverse_geocode_cb)(maps_error_e result, int request_id, int index, int total, maps_address_h address, void *user_data)

Called when the address information is converted from position information.

The Maps Service invokes this callback when the address is obtained from the specified coordinates.
If search is failed, the value of total is 0 and address is NULL.

Since :

2.4

Remarks:

The parameter address must be released using maps_address_destroy().
This error code will be reported.
MAPS_ERROR_NONE
MAPS_ERROR_OUT_OF_MEMORY
MAPS_ERROR_INVALID_PARAMETER
MAPS_ERROR_NOT_FOUND.

Parameters:

[in]	result	The result of request
[in]	request_id	The ID of request
[in]	index	The current index of address data in result set, start from 0
[in]	total	The total number of results
[in]	address	The requested address information
[in]	user_data	The user data passed from maps_service_reverse_geocode()

Precondition:

maps_service_reverse_geocode() will invoke this callback.

See also:

maps_service_reverse_geocode()

maps_service_cancel_request()

---

Function Documentation

int maps_service_geocode	(	const maps_service_h	maps,
		const char *	address,
		const maps_preference_h	preference,
		maps_service_geocode_cb	callback,
		void *	user_data,
		int *	request_id
	)

Gets the position coordinates for a given address.
The request is asynchronous.

This function obtains position coordinates for a given free-formed address string.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the request, use maps_service_cancel_request().
To check if Maps Provider is capable of geocoding, use maps_service_provider_is_service_supported() with MAPS_SERVICE_GEOCODE passed as service parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	address	The free-formed address
[in]	preference	The set of preferences for processing geocoding
[in]	callback	The callback which will receive position coordinates
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and obtain its handle.

Postcondition:

It invokes maps_service_geocode_cb() to deliver obtained position coordinates.

See also:

maps_service_geocode_inside_area()

maps_service_geocode_cb()

maps_service_cancel_request()

maps_service_reverse_geocode()

maps_service_provider_is_service_supported()

int maps_service_geocode_by_structured_address	(	const maps_service_h	maps,
		const maps_address_h	address,
		const maps_preference_h	preference,
		maps_service_geocode_cb	callback,
		void *	user_data,
		int *	request_id
	)

Gets the position coordinates for a given address.
The request is asynchronous.

This function obtains position coordinates for a given structured address.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the request, use maps_service_cancel_request().
To check if Maps Provider is capable of geocoding by structured address, use maps_service_provider_is_service_supported() with MAPS_SERVICE_GEOCODE_BY_STRUCTURED_ADDRESS passed as service parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	address	The structured address
[in]	preference	The set of preferences for processing geocoding
[in]	callback	The callback which will receive position coordinates
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and obtain its handle.

Postcondition:

It invokes maps_service_geocode_cb() to deliver obtained position coordinates.

See also:

maps_service_geocode()

maps_service_geocode_inside_area()

maps_service_geocode_cb()

maps_service_cancel_request()

maps_service_reverse_geocode()

maps_service_provider_is_service_supported()

int maps_service_geocode_inside_area	(	const maps_service_h	maps,
		const char *	address,
		const maps_area_h	bounds,
		const maps_preference_h	preference,
		maps_service_geocode_cb	callback,
		void *	user_data,
		int *	request_id
	)

Gets the position for a given address within the specified bounding box.
The request is asynchronous.

This function obtains position coordinates for a given free-formed address string within the specified bounding box.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

Polygonal bounding box is not supported.
To cancel the request, use maps_service_cancel_request().
To check if Maps Provider is capable of geocoding inside area, use maps_service_provider_is_service_supported() with MAPS_SERVICE_GEOCODE_INSIDE_AREA passed as service parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	address	The free-formed address
[in]	bounds	The bounding box
[in]	preference	The set of preferences for processing geocoding
[in]	callback	The callback which will receive position coordinates
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and obtain its handle.

Postcondition:

It invokes maps_service_geocode_cb() to deliver obtained position coordinates.

See also:

maps_service_geocode_by_structured_address()

maps_service_geocode_inside_area()

maps_service_geocode_cb()

maps_service_geocode()

maps_service_cancel_request()

maps_service_reverse_geocode()

maps_service_provider_is_service_supported()

int maps_service_multi_reverse_geocode	(	const maps_service_h	maps,
		maps_coordinates_list_h	coordinates_list,
		const maps_preference_h	preference,
		maps_service_multi_reverse_geocode_cb	callback,
		void *	user_data,
		int *	request_id
	)

Gets the address list for a given position coordinates list.
The request is asynchronous.

This function obtains structured address information.

Since :

3.0

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the request, use maps_service_cancel_request().
To check if Maps Provider is capable of multi reverse geocoding, use maps_service_provider_is_service_supported() with MAPS_SERVICE_MULTI_REVERSE_GEOCODE passed as service parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	coordinates_list	The coordinates list [2 ~ 100] (a set of coordinates)
[in]	preference	The set of preferences for processing Reverse Geocode
[in]	callback	The callback which will retrieve address list
[in]	user_data	The user data pointer to be passed to the callback
[out]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and obtain its handle.

Postcondition:

This function invokes maps_service_multi_reverse_geocode_cb().

See also:

maps_service_multi_reverse_geocode_cb()

maps_service_cancel_request()

maps_service_reverse_geocode()

maps_service_provider_is_service_supported()

int maps_service_reverse_geocode	(	const maps_service_h	maps,
		double	latitude,
		double	longitude,
		const maps_preference_h	preference,
		maps_service_reverse_geocode_cb	callback,
		void *	user_data,
		int *	request_id
	)

Gets the address for a given position coordinates.
The request is asynchronous.

This function obtains structured address information for a given position coordinates.

Since :

2.4

Privilege Level:

public

Privilege:

http://tizen.org/privilege/mapservice
http://tizen.org/privilege/internet
http://tizen.org/privilege/network.get

Remarks:

To cancel the request, use maps_service_cancel_request().
To check if Maps Provider is capable of reverse geocoding, use maps_service_provider_is_service_supported() with MAPS_SERVICE_REVERSE_GEOCODE passed as service parameter.

Parameters:

[in]	maps	The Maps Service handle
[in]	latitude	The latitude [-90.0 ~ 90.0] (degrees)
[in]	longitude	The longitude [-180.0 ~ 180.0] (degrees)
[in]	preference	The set of preferences for processing reverse geocoding
[in]	callback	The callback which will receive address information
[in]	user_data	The user data to be passed to the callback function
[out]	request_id	The ID of request

Returns:

0 on success, otherwise a negative error value

Return values:

MAPS_ERROR_NONE	Successful
MAPS_ERROR_INVALID_PARAMETER	Invalid parameter
MAPS_ERROR_NETWORK_UNREACHABLE	Network connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLE	Service not available
MAPS_ERROR_PERMISSION_DENIED	Permission Denied
MAPS_ERROR_NOT_SUPPORTED	Not supported
MAPS_ERROR_CONNECTION_TIME_OUT	Timeout error, no answer
MAPS_ERROR_INVALID_OPERATION	Operation is not valid
MAPS_ERROR_NOT_FOUND	Result not found
MAPS_ERROR_KEY_NOT_AVAILABLE	Invalid key
MAPS_ERROR_UNKNOWN	Unknown error

Precondition:

Call maps_service_create() to create Maps Service and obtain its handle.

Postcondition:

This function invokes maps_service_reverse_geocode_cb().

See also:

maps_service_reverse_geocode_cb()

maps_service_cancel_request()

maps_service_geocode()

maps_service_provider_is_service_supported()