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.
void | OGRGeocodeDestroySession (OGRGeocodingSessionH hSession)
| Destroys a session handle for geocoding requests.
OGRLayerH | OGRGeocode (OGRGeocodingSessionH hSession, const char *pszQuery, char **papszStructuredQuery, char **papszOptions)
| Runs a geocoding request.
OGRLayerH | OGRGeocodeReverse (OGRGeocodingSessionH hSession, double dfLon, double dfLat, char **papszOptions)
| Runs a reverse geocoding request.
void | OGRGeocodeFreeResult (OGRLayerH hLayer)
| Destroys the result of a geocoding request.

## 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().

## ◆ 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
  a handle that should be freed with OGRGeocodeDestroySession(), or NULL in case of failure.

## ◆ OGRGeocodeDestroySession()

void OGRGeocodeDestroySession | ( | OGRGeocodingSessionH | hSession | ) |

Destroys a session handle for geocoding requests.

Parameters

  hSession | the handle to destroy.

## ◆ OGRGeocodeFreeResult()

void OGRGeocodeFreeResult | ( | OGRLayerH | hLayer | ) |

Destroys the result of a geocoding request.

Parameters

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

## ◆ 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().