CNominatim v1.10

Welcome to CNominatim, a set of C++ classes to handle Nominatim queries. Nominatim is the search tool used by OpenStreetMap. For further information on Nominatim, please see http://wiki.openstreetmap.org/wiki/Nominatim. Nominatim is a web service provided by OpenStreetMap to convert addresses to locations on a map and the reverse also known as Geocoding which converts a lat / long point or specific OSM element to an address. It also allows lookup of specific OSM ids.

The classes provided are: Nominatim::CSearchQuery, Nominatim::CSearchPlace, Nominatim::CReverseGeocodingQuery, Nominatim::CReverseGeocodingQueryResult, Nominatim::CAddressLookupQuery, Nominatim::CLookupPlace & Nominatim::CNominatim. The three main methods provided are:

HRESULT Search(const CSearchQuery& query, CSearchPlaceArray& result, LPCTSTR pszServer = _T("nominatim.openstreetmap.org"), LPCTSTR pszURL = _T("search"))

The search method performs the address lookup query using the parameters specified in "query" and returns an array of results in "result" using the specified Nominatim server "sServer". The method returns a standard HRESULT code to indicate success or failure.

HRESULT ReverseGeocoding(const CNominatimReverseGeocodingQuery& query, CNominatimReverseGeocodingQueryResult& result, LPCTSTR pszServer = _T("nominatim.openstreetmap.org"), LPCTSTR pszURL = _T("reverse"))

The ReverseGeocoding method performs the reverse geocoding query using the parameters specified in "query" and returns the result in "result" using the specified Nominatim server "sServer". The method returns a standard HRESULT code to indicate success or failure.

HRESULT AddressLookup(const CAddressLookupQuery& query, CLookupPlaceArray& result, LPCTSTR pszServer = _T("nominatim.openstreetmap.org"), LPCTSTR pszURL = _T("lookup"))

The AddressLookup method performs the address lookup query using the parameters specified in "query" and returns the result in "result" using the specified Nominatim server "sServer". The method returns a standard HRESULT code to indicate success or failure.

Features

• Provides a simple C++ header only module to easily call the Nominatim web services.
• Supports all the parameters to both methods as documented at http://wiki.openstreetmap.org/wiki/Nominatim.
• Internally the classes use WinHTTP to hide the detail of calling the web services.
• The classes hides the details of downloading and parsing the XML response via MSXML6 and all response values are served up as simple C++ class variables.
• The HTTP user agent string can be customized via CNominatimSearchQuery::m_sUserAgent and CNominatimReverseGeocodingQuery::m_sUserAgent
• All errors are reported as a simple HRESULT value from the two main methods
• Supports using an existing HINTERNET session if your application already uses a specific session handle.

Usage

• To use the various CNominatim classes in your project simply #include nominatim.h from the test application in your application.
• If you are using the WinHttp support in CNominatim, then you will need to download the author's WinHttpWrappers classes from http://www.naughter.com/winhttpwrappers.html
• As of v1.06 the classes are only supported on VC 2017 or later.
• Included in the download is a VC 2017 console application which demonstrates the classes using the sample as mentioned on the Nominatim wiki page.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

v1.10 (5 June 2022)

• Updated the code to use C++ uniform initialization for all variable declarations
• Updated copyright details.

v1.09 (30 December 2021)

• Fixed an issue in _ReverseGeocoding where XML node values were not validated.

v1.08 (16 December 2021)

• Updated copyright details.
• Added support for polygon_threshold in Search query.
• Added support for Polygon output to Reverse query.
• Added support for polygon_threshold in Reverse query.
• Added support for Polygon output to Lookup query.
• Added support for polygon_threshold in Lookup query.

v1.07 (29 March 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.06 (22 November 2018)

• Updated copyright details
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.
• Replaced enum throughout the codebase with enum class
• Removed code path which supported CNOMINATIM_MFC_EXTENSIONS define
• Removed code path which supported WINHTTPWRAPPERS_MFC_EXTENSIONS define
• Reworked code to use ATL::CComPtr instead of #import
• Removed code path which supported CNOMINATIM_NOWINHTTP

v1.05 (8 October 2017)

• Renamed CNominatimString typedef to String
• Added typedefs for the CSearchPlace and CLookupPlace arrays

v1.04 (8 October 2017)

• Updated copyright details.
• Replaced NULL throughout the codebase with nullptr. This means that the minimum requirement for the framework is now VC 2010.
• Replaced CString::operator LPC*STR() calls throughout the codebase with CString::GetString calls
• Updated the sample app to include a HTTP user-agent in the request.
• Reworked the classes to optionally compile without MFC. By default the classes now use STL classes and idioms but if you define CNOMINATIM_MFC_EXTENSIONS the classes will revert back to the MFC behaviour.
• Replaced BOOL throughout the codebase with bool
• Added SAL annotations to all the codebase
• Added support for the dedupe flag to the Search method
• Added support for extratags and namedetails to the ReverseGeocoding method
• Eliminated usage of AfxGetAppName from CreateSession method

v1.03 (8 November 2015)

• Updated copyright details.
• Updated code to work with the latest version of the author's WinHTTPWrappers classes.
• Updated code to compile cleanly on VC 2010, 2013 & 2015.
• Reworked the CNominatim::Search and CNominatim::AddressLookup methods to pass the details of the Nominatim server to use as a MFC CString.
• Added support for street, city, county, state, country, postalcode, countrycodes, bounded, extratags & namedetails parameters to Search method.
• Added support for to extratags & namedetails parameters to AddressLookup method.
• All the classes have been renamed and moved into a Nominatim namespace.
• The CNominatim::AddressLookup method has been renamed to ReverseGeocoding
• Added support for the Nominatim AddressLookup API

v1.02 (21 July 2013)

• Updated copyright details
• Updated the code to use the new names of the author's WinHTTP wrapper classes. Thanks to Christopher Hrabia for reporting this issue.

v1.01 (7 August 2011)

• Updated the code to support WinHTTP for downloads in addition to Wininet. By default the class now uses WinHttp unless you define CNOMINATIM_NOWINHTTP before you include "cnominatim.h"
• Updated copyright details
• Fixed a /analyze compiler warning in the Wininet version of CreateRequest

v1.0 (24 October 2010)

• Initial Public release

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
5 June 2022