Tizen Native API  4.0

This provides APIs for Geocoder Service.

Related Features

This API is related with the following features:

  • http://tizen.org/feature/network.internet
    It is recommended to design feature related codes in your application for reliability.
    You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
    To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
    More details on featuring your application can be found from Feature Element.

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.3.2
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]resultThe result of request
[in]request_idThe ID of request
[in]indexThe current index of coordinates in result set, start from 0
[in]totalThe total number of results
[in]coordinatesThe coordinates of the place
[in]user_dataThe 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 :
2.3.2
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]resultThe result of request
[in]request_idThe ID of request
[in]totalThe total number of results
[in]address_listThe converted address list from the requested coordinates list
[in]user_dataThe 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.3.2
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]resultThe result of request
[in]request_idThe ID of request
[in]indexThe current index of address data in result set, start from 0
[in]totalThe total number of results
[in]addressThe requested address information
[in]user_dataThe 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.3.2
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]mapsThe Maps Service handle
[in]addressThe free-formed address
[in]preferenceThe set of preferences for processing geocoding
[in]callbackThe callback which will receive position coordinates
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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.3.2
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]mapsThe Maps Service handle
[in]addressThe structured address
[in]preferenceThe set of preferences for processing geocoding
[in]callbackThe callback which will receive position coordinates
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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.3.2
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]mapsThe Maps Service handle
[in]addressThe free-formed address
[in]boundsThe bounding box
[in]preferenceThe set of preferences for processing geocoding
[in]callbackThe callback which will receive position coordinates
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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 :
2.3.2
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]mapsThe Maps Service handle
[in]coordinates_listThe coordinates list [2 ~ 100] (a set of coordinates)
[in]preferenceThe set of preferences for processing Reverse Geocode
[in]callbackThe callback which will retrieve address list
[in]user_dataThe user data pointer to be passed to the callback
[out]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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.3.2
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]mapsThe Maps Service handle
[in]latitudeThe latitude [-90.0 ~ 90.0] (degrees)
[in]longitudeThe longitude [-180.0 ~ 180.0] (degrees)
[in]preferenceThe set of preferences for processing reverse geocoding
[in]callbackThe callback which will receive address information
[in]user_dataThe user data to be passed to the callback function
[out]request_idThe ID of request
Returns:
0 on success, otherwise a negative error value
Return values:
MAPS_ERROR_NONESuccessful
MAPS_ERROR_INVALID_PARAMETERInvalid parameter
MAPS_ERROR_NETWORK_UNREACHABLENetwork connection failed
MAPS_ERROR_SERVICE_NOT_AVAILABLEService not available
MAPS_ERROR_PERMISSION_DENIEDPermission Denied
MAPS_ERROR_NOT_SUPPORTEDNot supported
MAPS_ERROR_CONNECTION_TIME_OUTTimeout error, no answer
MAPS_ERROR_INVALID_OPERATIONOperation is not valid
MAPS_ERROR_NOT_FOUNDResult not found
MAPS_ERROR_KEY_NOT_AVAILABLEInvalid key
MAPS_ERROR_UNKNOWNUnknown 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()