There's a FindAddress function that takes a structured address parameter object, which has fields for house number, street, city, postal code, etc.. Here's what it looks like in all 4 APIs:

C++: TResult CFramework::FindAddress(const CAddress& aAddress,CPointerArray<CBaseMapObject>& aObjectArray,int32 aMaxObjectCount,bool aFuzzy)
.NET: Result FindAddress(Address aAddress,List<MapObject> aObjectList,int aMaxObjectCount,bool aFuzzy)
Android: MapObject[] findAddress(Address aAddress,int aMaxObjectCount,boolean aFuzzy)
iOS: -(CTResult)find:(NSMutableArray*)aObjectArray withAddress:(CartoTypeAddress*)aAddress maxItems:(int)aMaxItems fuzzy:(bool)aFuzzy

  • The fuzzy-match system, turned on using the aFuzzy parameter, is fast enough to be used on large maps. It returns objects with a small edit distance from the desired text. For example, you can find Rio de Janeiro using misspellings like "Rio de Janiero", "Rio de Janiro", etc.
  • Returned places are sorted by relevance.
  • If you search for a street address, and the system finds one or more buildings or streets, you won't get irrelevant places like the locality: it's obvious that you want buildings if possible. For example, if you search for building = 23, street = Acacia Avenue, city = Anytown, your results will include 'Anytown' only if the building or street isn't found.

The image above shows the Espadeiro restaurant in Rio de Janeiro, Brazil, found using 'Espadeiro' in the building field, and just 'Rio' in the locality field. It was returned as the first (most relevant) search result.

partial matching...

is enabled only if you create a CTM1 file containing a full text index. That's easy: use /textindex=full (the default) with the makemap tool. Then you'll be able to seach for any phrase within a name, and use standard abbreviations, too, like St for Street. The abbreviation system supports English, Spanish, French, German, Catalan, and Danish at present.

As you might expect, partial matches are treated as less relevant than full matches.

data quality

Data quality is important. If address matching fails or produces incorrect results, please let us know, particularly if the example is small and easily reproducible, but bear in mind that OpenStreetMap data, which most CartoType applications use, is very variable and incomplete. In particular, most cities and towns are represented by center points, not polygons, so CartoType has to decide whether a street is in a certain town by measuring its straight-line distance from the center point, which usually works fine, but occasionally gives unwanted results.