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
4c. Use the optional
Better:
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.
X
Not Good:
B
Better:
Berlin
1. DO separate the parts of the location with a comma and a space.
X
Not Good:
Trierer Straße 15 99423 Weimar Deutschland
X
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.
X
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.
X
Not Good:
Corner of 4th and Main St, Some Town
Better:
27 Main Street, Some Town, Country
4. DO tell us which country you mean
4a. Include the country name (in English or the local language) in the query
X Not Good:Trierer Straße 15, 99423, Weimar
Better:
Trierer Straße 15, 99423, Weimar, Deutschland
4b. DO NOT just append the ISO countrycode to the query
X Not Good:Trierer Straße 15, 99423, Weimar, DE
Better:
Trierer Straße 15, 99423, Weimar, Germany
ISO codes in free text can be ambigious (does
CA
mean Canada or California)?
4c. Use the optional
countrycode
parameter
Better:
&countrycode=de
Learn more about the optional
countrycode parameter.
5. DO remove unneeded formatting or abbreviations
X
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.
X
Not Good:
720 VETERANS BLVD; STE 100, City, Country
Better:
720 VETERANS Boulevard, City, Country
7. DO NOT send us undefined values
We often see people send us queries that include
undefined
or
NaN
or just empty fields.
X
Not Good:
undefined,Pueblo,CO,81003
X
Not Good:
,,,CO,81003
X
Not Good:
none,none,none,CO,81003
X
Not Good:
-,-,-,CO,81003
X
Not Good:
NULL,NULL,NULL,CO,81003
Better:
Pueblo, CO, 81003, USA
8. DO NOT send us placeholders
There is no need to send us things like XXXX for unknown postcode digits.
X
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.
X
Not Good:
77 Massachusetts Ave, Cambridge, MA 2142, USA
Better:
77 Massachusetts Ave, Cambridge, MA 02142, USA
10. 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 services allows 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.
X
Not Good:
APO AE 09180, USA
11. 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
12. 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.
X
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
13. 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.
X
Not Good:
Köln
Better:
K%C3%B6ln
X
Not Good:
Thành phố Hà Nội
Better:
Th%C3%A0nh%20ph%E1%BB%91%20H%C3%A0%20N%E1%BB%99i
14. 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.
X
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 it to be?