The geocoding API exposes a single method find which can be invoked by the following URL:

http://geocoding.cloudmade.com/YOUR-API-KEY/geocoding/v2/find.output_type?query=search_query&parameters

Examples

Please note that the geocoding API expects UTF-8 encoding. Most browsers (except Chrome) do not encode query params as UTF-8, so you will need to adjust their settings if you want to test names that contain characters such as å, ü, Cyrillic characters etc. In Firefox, this is done by opening about:config URL and setting network.standard-url.encode-query-utf8 = true

Geocoding an address
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.js?query=Fleet+street,+London,+UK
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.html?query=Fleet+street,+London,+UK

Searching for a street or road whose name contains "temple"
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.js?object_type=road&around=51.51384,-0.10952&distance=closest&query=temple
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.html?object_type=road&around=51.51384,-0.10952&distance=closest&query=temple

Searching for all hotels around a point
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.js?object_type=hotel&around=51.51384,-0.10952&distance=2000&results=10
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.html?object_type=hotel&around=51.51384,-0.10952&distance=2000&results=10

Searching for all parks around an address:
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.js?around=city:london;country:uk&object_type=park
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.html?around=city:london;country:uk&object_type=park

Reverse geocoding
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.js?around=51.51384,-0.10952&distance=closest&object_type=address
http://geocoding.cloudmade.com/BC9A493B41014CAABB98F0471D759707/geocoding/v2/find.html?around=51.51384,-0.10952&distance=closest&object_type=address

Query

search_query, if present, specifies an address to geocode, or a keyword used to search for objects whose name contains the keyword.

If the query represents an address, it can either be in free form format (for example, query=Oxford+st,+London,+UK), or specified as a set of address parts separated by semicolon. The following address parts are recognized: poi, house, street, city, zipcode or postcode, county, country. For example, query=street:Oxford street;city:London;country:UK.

For queries representing a keyword, search is case-insensitive, matching whole words. Wildcards are not currently supported.

Parameters

Parameter Explanation Default
results Number of results to return. 10
skip Number of results to skip from beginning. 0
return_geometry Set it to true if you want geometry included in search results. false
return_location Set it to true if you do want location information like road, city, county, country, postcode in returned results. false
bbox Bounding box of the search area. Format: southern_latitude,western_longitude,northern_latitude,eastern_longitude. Cannot be used together with around / distance.
around Center point of the search area. Used together with distance. around must be an EPSG:4326 coordinate ("latitude,longitude") or an address. Cannot be used together with bbox. If used together with a non-empty search_query, only one may specify an address.
distance Radius of the search area. Distance is specified in meters from the center point. Special value closest limits search results to one, closest to the center point of the search area. 100 meters
bbox_only Used only if bbox is specified. If set to false, the geocoder will return results from the whole planet, but still ranking results from within the specified bbox higher, otherwise only results from within the specified bbox will be returned. true
object_type Limits search results to a specific object type. Full list of object types can be found here. If around / distance is specified, the default is address.

Output type

Output type can either be ".js" for JSON, ".geojs" for GeoJSON or ".html" to render search results on the map (useful for debug purposes).