C API for geocoding client. More...

#include "cpl_port.h"
#include "ogr_api.h"

Typedefs
typedef struct _OGRGeocodingSessionHS *	OGRGeocodingSessionH
	Opaque type for a geocoding session.

Functions
OGRGeocodingSessionH	OGRGeocodeCreateSession (char **papszOptions)
	Creates a session handle for geocoding requests. More...

void	OGRGeocodeDestroySession (OGRGeocodingSessionH hSession)
	Destroys a session handle for geocoding requests. More...

OGRLayerH	OGRGeocode (OGRGeocodingSessionH hSession, const char pszQuery, char papszStructuredQuery, char *papszOptions)
	Runs a geocoding request. More...

OGRLayerH	OGRGeocodeReverse (OGRGeocodingSessionH hSession, double dfLon, double dfLat, char **papszOptions)
	Runs a reverse geocoding request. More...

void	OGRGeocodeFreeResult (OGRLayerH hLayer)
	Destroys the result of a geocoding request. More...

Detailed Description

C API for geocoding client.

Function Documentation

◆ OGRGeocode()

OGRLayerH OGRGeocode	(	OGRGeocodingSessionH	hSession,
		const char *	pszQuery,
		char **	papszStructuredQuery,
		char **	papszOptions
	)

Runs a geocoding request.

If the result is not found in cache, a GET request will be sent to resolve the query.

Note: most online services have Term of Uses. You are kindly requested to read and follow them. For the OpenStreetMap Nominatim service, this implementation will make sure that no more than one request is sent by second, but there might be other restrictions that you must follow by other means.

In case of success, the return of this function is a OGR layer that contain zero, one or several features matching the query. Note that the geometry of the features is not necessarily a point. The returned layer must be freed with OGRGeocodeFreeResult().

Note: this function is also available as the SQL ogr_geocode() function of the SQL SQLite dialect.

The list of recognized options is :

ADDRESSDETAILS=0 or 1: Include a breakdown of the address into elements Defaults to 1. (Known to work with OSM and MapQuest Nominatim)
COUNTRYCODES=code1,code2,...codeN: Limit search results to a specific country (or a list of countries). The codes must fellow ISO 3166-1, i.e. gb for United Kingdom, de for Germany, etc.. (Known to work with OSM and MapQuest Nominatim)
LIMIT=number: the number of records to return. Unlimited if not specified. (Known to work with OSM and MapQuest Nominatim)
RAW_FEATURE=YES: to specify that a 'raw' field must be added to the returned feature with the raw XML content.
EXTRA_QUERY_PARAMETERS=params: additional parameters for the GET request.

Parameters

hSession	the geocoding session handle.
pszQuery	the string to geocode.
papszStructuredQuery	unused for now. Must be NULL.
papszOptions	a list of options or NULL.

Returns: a OGR layer with the result(s), or NULL in case of error. The returned layer must be freed with OGRGeocodeFreeResult().

Since: GDAL 1.10

◆ OGRGeocodeCreateSession()

OGRGeocodingSessionH OGRGeocodeCreateSession ( char ** papszOptions )

Creates a session handle for geocoding requests.

Available papszOptions values:

"CACHE_FILE" : Defaults to "ogr_geocode_cache.sqlite" (or otherwise "ogr_geocode_cache.csv" if the SQLite driver isn't available). Might be any CSV, SQLite or PostgreSQL datasource.
"READ_CACHE" : "TRUE" (default) or "FALSE"
"WRITE_CACHE" : "TRUE" (default) or "FALSE"
"SERVICE": "OSM_NOMINATIM" (default), "MAPQUEST_NOMINATIM", "YAHOO", "GEONAMES", "BING" or other value. Note: "YAHOO" is no longer available as a free service.
"EMAIL": used by OSM_NOMINATIM. Optional, but recommended.
"USERNAME": used by GEONAMES. Compulsory in that case.
"KEY": used by BING. Compulsory in that case.
"APPLICATION": used to set the User-Agent MIME header. Defaults to GDAL/OGR version string.
"LANGUAGE": used to set the Accept-Language MIME header. Preferred language order for showing search results.
"DELAY": minimum delay, in second, between 2 consecutive queries. Defaults to 1.0.
"QUERY_TEMPLATE": URL template for GET requests. Must contain one and only one occurrence of %s in it. If not specified, for SERVICE=OSM_NOMINATIM, MAPQUEST_NOMINATIM, YAHOO, GEONAMES or BING, the URL template is hard-coded.
"REVERSE_QUERY_TEMPLATE": URL template for GET requests for reverse geocoding. Must contain one and only one occurrence of {lon} and {lat} in it. If not specified, for SERVICE=OSM_NOMINATIM, MAPQUEST_NOMINATIM, YAHOO, GEONAMES or BING, the URL template is hard-coded.

All the above options can also be set by defining the configuration option of the same name, prefixed by OGR_GEOCODE_. For example "OGR_GEOCODE_SERVICE" for the "SERVICE" option.

Parameters

papszOptions NULL, or a NULL-terminated list of string options.

Returns: an handle that should be freed with OGRGeocodeDestroySession(), or NULL in case of failure.

Since: GDAL 1.10

◆ OGRGeocodeDestroySession()

void OGRGeocodeDestroySession ( OGRGeocodingSessionH hSession )

Destroys a session handle for geocoding requests.

Parameters

hSession the handle to destroy.

Since: GDAL 1.10

◆ OGRGeocodeFreeResult()

void OGRGeocodeFreeResult ( OGRLayerH hLayer )

Destroys the result of a geocoding request.

Parameters

hLayer the layer returned by OGRGeocode() or OGRGeocodeReverse() to destroy.

Since: GDAL 1.10

◆ OGRGeocodeReverse()

OGRLayerH OGRGeocodeReverse	(	OGRGeocodingSessionH	hSession,
		double	dfLon,
		double	dfLat,
		char **	papszOptions
	)

Runs a reverse geocoding request.

If the result is not found in cache, a GET request will be sent to resolve the query.

Note: most online services have Term of Uses. You are kindly requested to read and follow them. For the OpenStreetMap Nominatim service, this implementation will make sure that no more than one request is sent by second, but there might be other restrictions that you must follow by other means.

In case of success, the return of this function is a OGR layer that contain zero, one or several features matching the query. The returned layer must be freed with OGRGeocodeFreeResult().

Note: this function is also available as the SQL ogr_geocode_reverse() function of the SQL SQLite dialect.

The list of recognized options is :

ZOOM=a_level: to query a specific zoom level. Only understood by the OSM Nominatim service.
RAW_FEATURE=YES: to specify that a 'raw' field must be added to the returned feature with the raw XML content.
EXTRA_QUERY_PARAMETERS=params: additional parameters for the GET request for reverse geocoding.

Parameters

hSession	the geocoding session handle.
dfLon	the longitude.
dfLat	the latitude.
papszOptions	a list of options or NULL.

Returns: a OGR layer with the result(s), or NULL in case of error. The returned layer must be freed with OGRGeocodeFreeResult().

Since: GDAL 1.10

Typedefs

Functions

Detailed Description

Function Documentation

◆ OGRGeocode()

◆ OGRGeocodeCreateSession()

◆ OGRGeocodeDestroySession()

◆ OGRGeocodeFreeResult()

◆ OGRGeocodeReverse()