CartoType has functions to find addresses and perform geocoding, which is converting a position to an address. You can try out these functions using the Windows demo. Use the 'Find address' menu item in the 'Find' menu to find an address. You can fill in any of the fields. Just leave fields blank if they are not needed or the information is unknown. Searching is faster if you provide the city, state, county, or province when searching for a street address.

Right-click anywhere on the map to geocode the position. CartoType geocodes the nearest object which might have an address. If you click one or near a building it will try to create an address for that building.

The parts of an address

CartoType returns an address as up to ten different parts:

Building

The building number or name, or both. If both are provided, they are separated by a comma, with the number second.

Feature

A land or water feature like a park, hill, or lake.

Street

The street or road which the building is on. This is sometimes indicated in the map data, but if not, CartoType uses the nearest named street.

Subsidiary locality (sub-locality)

The suburb or neighbourhood if any.

Locality

The nearest town or city, or the enclosing town or city if polygons are used in the map.

Island

The enclosing island if any.

Subsidiary administrative area (sub-admin-area)

The lower-level administrative area: in OpenStreetMap terms this is a level-6 boundary: US or UK county, German Landkreis or Kreis, Frenche département, etc.

Administrative area

The higher-level administrative area: in OpenStreetMap terms this is a level-4 boundary: US state, UK constituent nation (England, Scotland, Wales or Northern Ireland), German Bundesland, French region, etc.

Country

The nation, including overseas constituent states.

Postal code

Postal codes (e.g., UK postcodes or US ZIP codes) are obtained using the best available information: the postal code attribute of a map object, or the enclosing postal code polygon if any, or the nearest postal code point. CartoType can import postcode data from GeoNames when creating maps.

APIs for geocoding and finding addresses

This section describes the main C++ API functions. For the other three APIs (.NET, iOS and Android) please see the relevant pages for those platforms. All four APIs are almost identical.

The CartoType::CAddress object is used both for providing addresses, when searching for them, and returning them. It is just a collection of strings for the different parts of the address as described above:

class CAddress
   {
   public:
   CT_IMPORT void Clear();
   CT_IMPORT TResult Append(MString& aDest,int32 aMaxItems = INT32_MAX,const TPointFP* aLocation = NULL,bool aLabel = false);
    
   /** The name or number of the building. */
   CString iBuilding;
   /** The name of a feature or place of interest. */
   CString iFeature;
   /** The street, road or other highway. */
   CString iStreet;
   /** The suburb, neighborhood, quarter or other subdivision of the locality. */
   CString iSubLocality;
   /** The village, town or city. */
   CString iLocality;
   /** The name of an island. */
   CString iIsland;
   /**
   The subsidiary administrative area: county, district, etc.
   By preference this is a level-6 area in the OpenStreetMap classification.
   Levels 7, 8 and 5 are used in that order if no level-6 area is found.
   */
   CString iSubAdminArea;
   /**
   The administrative area: state, province, etc.
   By preference this is a level-4 area in the OpenStreetMap classification.
   Level 3 is used if no level-4 area is found.
   */
   CString iAdminArea;
   /** The country. */
   CString iCountry;
   /** The postal code. */
   CString iPostCode;
   };

To find an address, use:

TResult CFramework::FindAddress(const CAddress& aAddress,CPointerArray<CBaseMapObject>& aObjectArray,int32 aMaxObjectCount,bool aFuzzy)

The found objects are returned, in approximate order of relevance, in aObjectArray. aMaxObjectCount is the maximum number of objects to return, and aFuzzy tells CartoType to use fuzzy string matching. You need to fill in at least one of the fields in aAddress.

If you want to give the user some help in filling in the fields, you can provide an incrementally-matched list of probable names by calling this function:

/**
Find part of an address used in a CAddress object, using the same search rules used for finding an entire address.
If aIncremental is true, prefix-matching is used and this enables an address dialog to be populated incrementally;
in this case it's a good idea to set aMaxObjectCount to a small number that is a suitable number of items to be displayed in
a list box on the display, for example 20.
*/
TResult CFramework::FindAddressPart(const MString& aText,TAddressPart aAddressPart,CPointerArray<CBaseMapObject>& aObjectArray,
 int32 aMaxObjectCount,bool aFuzzy,bool aIncremental)

To geocode by converting a location into an address, use

/**
Create an address for a point in the map.
If aLocale is non-null it is used when getting names.
If aLocale is null or empty, the locale set by SetLocale is used.
*/
TResult CFramework::GetAddress(CAddress& aAddress,double aX,double aY,TCoordType aCoordType,const char* aLocale)

and to geocode from a map object, which will in practice always be one that was returned by one of the Find functions, use

/**
Create an address for a map object.
If aLocale is non-null it is used when getting names.
If aLocale is null or empty, the locale set by SetLocale is used.
*/
CT_EXPORT TResult CFramework::GetAddress(CAddress& aAddress,const CBaseMapObject& aMapObject,const char* aLocale)
 {
 if (!aLocale || !(*aLocale))
 aLocale = iLocale;
 return iMap->GetAddress(aAddress,aMapObject,aLocale,iMapDrawParam);
 }

Bulk geocoding

The geocoding API functions described above are very convenient for interactive applications where the user can click on the map to get an address. However, you can also use them for bulk geocoding, without the need to draw a map or create an interactive application. Just load a map in, call GetAddress with each location in your list, and write the results to a file.