Formatting your geocoding query

Step by step guide to formatting your geocoding query

1. DO make sure your query is long enough

   The query must be at least two characters long, we can not provide a meaniningful answer for a single character query.

   Not Good: B

   Better: Berlin

2. DO separate the parts of the location with a comma and a space.

   Not Good: Trierer Straße 15 99423 Weimar Deutschland

   Not Good: Trierer Straße 15,99423,Weimar,Deutschland

   Better: Trierer Straße 15, 99423, Weimar, Deutschland

3. Send us only places/addresses

   This might sound obvious, but we often see people geocoding lists of addresses - including the name of the resident or complex company names. That just confuses things.

   Not Good: Mr. Jack London, Trierer Straße 15, 99423, Weimar, Germany

   Better: Trierer Straße 15, 99423, Weimar, Germany

   This is the most common mistake we see with forward geocoding. Leave out everything that is not part of the address.

4. DO NOT send us "intersections"

   Sometimes people want to send us intersections, this is not a format we support.

   Not Good: Corner of 4th and Main St, Some Town

   Better: 27 Main Street, Some Town, Country

5. DO tell us which country you mean

   • Include the country name (in English or the local language) in the query

     Not Good: Trierer Straße 15, 99423, Weimar

     Better: Trierer Straße 15, 99423, Weimar, Deutschland

   • DO NOT just append the ISO countrycode to the query

     Not Good: Trierer Straße 15, 99423, Weimar, DE

     Better: Trierer Straße 15, 99423, Weimar, Germany

     ISO codes in free text can be ambiguous. Does CA mean Canada or California? Does DE mean Germany or Delaware?

   • Use the optional countrycode parameter

     Better: &countrycode=de

     Learn more about the optional countrycode parameter.

6. DO remove unneeded formatting or abbreviations

   Not Good: Trierer Straße 15\n99423 Weimar\n

   Better: Trierer Straße 15, 99423, Weimar, Deutschland

   Remove things like c/o (common abbreviation for 'care of'), or PO BOX that do not actually specify the location.

7. DO remove unneeded address information

   An extension of the rule above. Each additional word increases the chance of confusing things, so if possible remove unhelpful address information like "Floor" or "Suite" or "Apt" that don't help with determining the location.

   Not Good: 720 VETERANS BLVD; STE 100, City, Country

   Better: 720 VETERANS Boulevard, City, Country

8. DO NOT send us undefined values

   We often see people send us queries that include undefined or NaN or MISSING or just empty fields.

   Not Good: undefined,Pueblo,CO,81003

   Not Good: ,,,CO,81003

   Not Good: none,none,none,CO,81003

   Not Good: -,-,-,CO,81003

   Not Good: NULL,NULL,NULL,CO,81003

   Better: Pueblo, CO, 81003, USA

9. DO NOT send us placeholders

   There is no need to send us things like XXXX for unknown postcode digits.

   Not Good: Augartenstrasse 26-28, Wien, xxxx, Österreich

   Better: Augartenstrasse 26-28, Wien, Österreich

10. DO NOT just send us postal codes and expect us to magically know which country you mean

    Many countries have five or four digit postal codes. If you just send us a string of numbers we have no idea which country you are referring to. Instead add the country to the query.

    Not Good: 08017

    Better: 08017, Spain

11. DO treat postal codes as strings, not numbers

    We often see queries with four digit postal codes when they should be five because the leading 0 has been removed. Somewhere along the way it was treated as a number rather than a string. If you know postal codes should be five digits add a check to ensure you are only sending us five digit strings.

    Not Good: 77 Massachusetts Ave, Cambridge, MA 2142, USA

    Better: 77 Massachusetts Ave, Cambridge, MA 02142, USA

12. DO NOT send us non-geographic addresses

    Many countries have postal identifiers (postcodes, state codes) that represent non-geographic addresses. As an example, the US postal service has the states codes AA, AE, AP for American military postal addresses. These do not correspond to any fixed location and thus can not be geocoded, though they are entirely valid addresses. It's better to not even send them to us.

    Not Good: APO AE 09180, USA

13. DO NOT send us things like URLs or code

    Occasionally people intentionally or unintentionally try to "help us" by sending us software code or URLs in their queries. When we see this we will reject your request with response code 400 - missing or bad query.

    Not Good: javascript:alert();some address

    Better: an actual address or placename

14. DO NOT send us overly long queries.

    If your query is too long or contains too many logical units we will reject your request with response code 400 - query too long.

    Not Good: some very very very very very very very very very very very very long long long long long long long long long address

    Better: some normal address

15. DO URL encode the query

    Once you've done everything else, please make sure you URL encode the query. Most programming languages have a standard library for URL encoding (sometimes also known as "percent encoding". Please use it, don't try to invent your own.

    Not Good: Köln

    Better: K%C3%B6ln

    Not Good: Thành phố Hà Nội

    Better: Th%C3%A0nh%20ph%E1%BB%91%20H%C3%A0%20N%E1%BB%99i

16. DO NOT double URL encode the query

    Occasionally we've seen people encode the query themselves, and then the library they are using encodes the request again.

    Not Good: K%25C3%25B6ln

    Good: K%C3%B6ln

    Please make sure you understand what the libraries you are using do. If you run into problems a good first step is to print the actual HTTP request URL you are sending to us. Is it what you expected?

17. DO NOT assume we support "fuzzy matching"

    Our geocoding API does not support "fuzzy matching". You can use our Geosearch service for that.

    Not Good: par

    Good: paris