Formatting your query

This guide lists steps you can take to format the forward geocoding queries you send to the OpenCage geocoding API.

This guide concerns only the required parameter q when forward geocoding (address to coordinates). Please see the API reference for information on reverse geocoding or on the various other optional parameters you can specify in your request.

Step by step guide to formatting your query

0. 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.

1. DO separate the parts of the location with a comma.

Not Good: Trierer Straße 15 99423 Weimar Deutschland

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

2. 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, Deutschland

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

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

3. 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

4. DO include the country in the query, and also please use the optional countrycode parameter

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

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

Learn more about the optional countrycode parameter.

5. 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.

6. 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

Better: 720 VETERANS Boulevard

7. DO NOT send us undefined values

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

Not Good: undefined,Lincolnton,NC,28092

Not Good: ,,,NC,28092

Not Good: none,none,none,NC,28092

Not Good: -,-,-,NC,28092

Not Good: NULL,NULL,NULL,NC,28092

Better: Lincolnton,NC,28092

8. DO NOT send us placeholders

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

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

Better: Augartenstrabe 26-28, Wien, Österreich

9. 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

10. 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: some address

11. 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

12. DO URL encode the query

Once you've done everything else, please make sure you URL encode the query. Most programming langauges 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

13. 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.

Good: K%C3%B6ln

Not Good: K%25C3%25B6ln

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 it to be?

Final thoughts

You might ask why you need to bother doing all this, surely we should catch common problems on our side? A fair question. We do try to catch obvious things of course. As you can imagine though, it's difficult for us know the pecularities of your data in your language and country. The more you can do to simplify, clean, and correct your queries, the better a chance we have to geocode correctly.

Happy geocoding!

Start your free trial

2,500 API requests per day.

No credit card required.