GDAL
Typedefs | Functions
ogr_geocoding.h File Reference

C API for geocoding client. More...

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

Go to the source code of this file.

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

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
hSessionthe geocoding session handle.
pszQuerythe string to geocode.
papszStructuredQueryunused for now. Must be NULL.
papszOptionsa 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
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
papszOptionsNULL, 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
void OGRGeocodeDestroySession ( OGRGeocodingSessionH  hSession)

Destroys a session handle for geocoding requests.

Parameters
hSessionthe handle to destroy.
Since
GDAL 1.10
void OGRGeocodeFreeResult ( OGRLayerH  hLayer)

Destroys the result of a geocoding request.

Parameters
hLayerthe layer returned by OGRGeocode() or OGRGeocodeReverse() to destroy.
Since
GDAL 1.10
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
hSessionthe geocoding session handle.
dfLonthe longitude.
dfLatthe latitude.
papszOptionsa 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

Generated for GDAL by doxygen 1.8.8.