World.geocode.xyz

Geocode.xyz

The Geocode.xyz Geocoding/Geoparsing API

This is a geocoding/geoparsing API. It receives text input and outputs location information in XML,CSV, JSON, GeoJSON Formats in the area of coverage. (see the Examples Section)
You may access this API either from your own code via a HTTP request (examples:
Reverse Geocoding:
curl 'https://geocode.xyz/51.50354,-0.12768?geoit=xml'
Geoparsing:
curl -X POST -d scantext="Ma io stasera volevo cenare al lume di candela, non cucinarci! #Milano #blackout" \
        -d geoit="XML" \
        https://geocode.xyz  
curl -X POST -d scantext="The Vienna Tourist Board [3] operates information and booking booths at the airport Arrival Hall, 7AM-11PM and in the center at 1., Albertinaplatz/Maysedergasse. Information and free maps are also avialable from the ÖBB InfoPoints and offices at train stations." \
        -d json="1" \
        https://geocode.xyz 
curl -X POST -d scantext="The most important museums of Amsterdam are located on the Museumplein, located at the southwestern side of the Rijksmuseum." \
        -d geojson="1" \
        https://geocode.xyz  
Forward Geocoding:
curl -X POST -d locate="London UK" \
        -d geoit="XML" \
        https://geocode.xyz
), or via a third party module (eg: Geo::Parser::Text)
What is Geocoding? Geocoding is an information retrieval process that is normally divided into Forward Geocoding and Reverse Geocoding


Forward Geocoding is the process of converting a place name (like "Plaza Volateria 3 Parque de Negocios Mas Blau I El Prat de Llobregat 08820 Spain") into geographic coordinates (like latitude 41.3189957000 and longitude 2.0746469000).


Reverse Geocoding is the process of converting a latitude,longitude point (like 41.3189957000, 2.0746469000 ) into the description of a location nearest to it (like 1 VOLATERIA Plaza, EL PRAT DE LLOBREGAT, ES)


The Geocode.xyz API provides a direct way to Forward and Reverse Geocode* or Geoparse* locations in text.

What is Geoparsing? Geoparsing is the process of identifying free-text descriptions of places and parsing out the place names from text. These places names are then geocoded to geographic coordinates expressed as latitude-longitude.


* Geocoding returns a single location coordinates (the match with the highest probability), while Geoparsing returns all locations matched ordered by confidence score.
Geo Projection (CRS) We use Web Mercator, also known as Google Web Mercator, Spherical Mercator, WGS 84 Web Mercator or WGS 84/Pseudo-Mercator.


Usage Limits

There are currently no usage limits but response times are normally throttled to no more than 1 request per second for un-authenticated users.

If that is too slow for you, get your own server on the Amazon Cloud using this AMI. Or obtain an API key for un-throttled access to the API.


Please note: Usage Limits for unauthenticated users may be changed at any time without further notice.

Geocoding API Request Format A Geocoding API request must be of the following form:


https://geocode.xyz/location?outputformat or https://geocode.xyz/?locate=location&outputformat


There are 4 possible output formats:

  1. https://geocode.xyz/41.3189957000,2.0746469000?json=1 ~ json (recommended) indicates output in JavaScript Object Notation (JSON)
  2. https://geocode.xyz/41.3189957,2.0746469?jsonp=1&callback=test ~ jsonp indicates output in "JSON with padding" (JSONp)
  3. https://geocode.xyz/1 VOLATERIA Plaza, EL PRAT DE LLOBREGAT?geoit=xml ~ xml indicates output as XML
  4. https://geocode.xyz/1 VOLATERIA Plaza, EL PRAT DE LLOBREGAT?geoit=csv ~ csv indicates output as CSV
If you have an API key for unthrottled access, include your key with the request,
eg: https://geocode.xyz/[request]&auth=[your api key]
Geoparsing API Request Format A Geoparsing API request must be of the following form:


https://geocode.xyz/?scantext={text}&outputformat


(you may also send text to the API via a POST method)

Geocoding and Geoparsing Lookups

Required parameters There is only one required parameter for single location geocoding - locate, and one required parameter for geoparsing - scantext.

You may pass the location to the API directly as in: https://geocode.xyz/location or via a parameter name as in: https://geocode.xyz/?locate=location
Parameter Name DescriptionPermitted Values
locate The location may be a street address in the areas of coverage in the EU, or similarly a latitude,longitude point in the EU. A string containing a free text location or a point expressed as a latitude,longitude pair (in that order!)
scantext Free form text containing locations. text

Output format options

If the output parameters are ommited, the output will default to html.
Otherwise you have five output options to choose from, as shown above (XML, JSON, JSONp, GeoJSON and CSV)
The output format may be set via the geoit parameter, which takes the following values:
  • geoit=XML
  • geoit=JSON
  • geoit=JSONp
  • geoit=GeoJSON
  • geoit=CSV
Optional parameters
Parameter Name DescriptionPermitted Values
region The region parameter defines the region/country to limit the search results for geoparsing functions (scantext) or single response geocoding (locate) Allowed Values: {AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BR, IO, VG, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CK, CR, HR, CU, CW, CY, CZ, CI, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KS, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, KP, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RO, RU, RW, RE, SH, KN, LC, PM, VC, BL, SX, MF, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, KR, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, UK, UM, US, UY, UZ, VU, VA, VE, VN, VI, WF, EH, YE, CD, ZM, ZW, }

For example: region=UK (limit to the UK) or region=FR (limit to France)
You may also submit more than one region codes divided by commas ",". For example: region=UK,FR (limit to either the UK or France).
To bias results to larger geographical areas, such as continents, use the following region names:

  • region=Europe (for Europe, including these countries that are broadly defined as European),
    AD     Andorra
    AL     Albania
    AM     Armenia
    AT     Austria
    AZ     Azerbaijan
    BA     Bosnia
    BE     Belgium
    BG     Bulgaria
    BY     Belarus
    CH     Switzerland
    CY     Cyprus
    CZ     Czech Republic
    DE     Germany
    DK     Denmark
    EE     Estonia
    ES     Spain
    FI     Finland
    FO     Faroe Islands
    FR     France
    GE     Georgia
    GR     Greece
    HR     Croatia
    HU     Hungary
    IE     Ireland
    IL     Israel
    IM     Isle of Man
    IS     Iceland
    IT     Italy
    KS     Kosovo
    LI     Liechtenstein
    LT     Lithuania
    LU     Luxembourg
    LV     Latvia
    MC     Monaco
    MD     Moldova
    ME     Montenegro
    MK     Macedonia
    MT     Malta
    NL     Netherlands
    NO     Norway
    PL     Poland
    PT     Portugal
    RO     Romania
    RS     Serbia
    RU     Russia
    SE     Sweden
    SI     Slovenia
    SK     Slovakia
    TR     Turkey
    UA     Ukraine
    UK     United Kingdom
    
    
  • region=Oceania (for Asian, Oceania countries such as Australia, New Zealand, etc
    AS 	 American Samoa
    AU 	 Australia
    CK 	 Cook Islands
    FJ 	 Fiji Islands
    FM 	 Federated States of Micronesia
    GU 	 Guam
    KI 	 Kiribati
    MH 	 Marshall Islands
    MP 	 Saipan
    NC 	 New Caledonia
    NF 	 Norfolk Island
    NR 	 Nauru
    NU 	 Niue
    NZ 	 New Zealand
    PF 	 French Polynesia
    PG 	 Papua New Guinea
    PW 	 Palau
    SB 	 Solomon Islands
    TK 	 Tokelau
    TL 	 East Timor
    TO 	 Tonga
    TV 	 Tuvalu
    UM 	 Wake Island
    VU 	 Vanuatu
    WF 	 Wallis and Futuna Islands
    WS 	 Samoa
    
    
    )
  • region=Asia (for the rest of Asia , except Oceania. There may be some overlap with Europe and Oceania)
    AE     United Arab Emirates
    AF     Afghanistan
    AM     Armenia
    AZ     Azerbaijan
    BD     Bangladesh
    BH     Bahrain
    BN     Brunei
    BT     Bhutan
    CC     Cocos Islands
    CN     China
    CX     Christmas Island
    GE     Georgia
    HK     Hong Kong
    ID     Indonesia
    IL     Israel
    IN     India
    IO     Diego Garcia
    IQ     Iraq
    IR     Iran
    JO     Jordan
    JP     Japan
    KG     Kyrgyzstan
    KH     Cambodia
    KP     North Korea
    KR     South Korea
    KW     Kuwait
    KZ     Kazakhstan
    LA     Laos
    LB     Lebanon
    LK     Sri Lanka
    MM     Myanmar
    MN     Mongolia
    MO     Macau
    MV     Maldives
    MY     Malaysia
    NP     Nepal
    OM     Oman
    PH     Philippines
    PK     Pakistan
    PS     Palestine
    QA     Qatar
    SA     Saudi Arabia
    SG     Singapore
    SY     Syria
    TH     Thailand
    TJ     Tajikistan
    TM     Turkmenistan
    TR     Turkey
    TW     Taiwan
    UZ     Uzbekistan
    VN     Vietnam
    YE     Yemen
    
    
  • region=SouthAmerica (or Latin America) Geocoding will be biased to these countries
    AR     Argentina
    BO     Bolivia
    BR     Brazil
    CL     Chile
    CO     Colombia
    EC     Ecuador
    GY     Guyana
    PE     Peru
    PY     Paraguay
    SR     Suriname
    UY     Uruguay
    VE     Venezuela
    
    
  • For North America you may simply pass region=US,CA,MX (Meaning USA, Canada and Mexico).
    Similarly, you may also bias geocoding to specific country subsets by using the country codes above.)
  • To further bias results to a specific city or cities, use the citybias parameter by passing city names separated by commas.

All supported countries of the World

The complete worldwide country list under the area of coverage (with official country names) is provided here:

AD     Andorra
AE     United Arab Emirates
AF     Afghanistan
AG     Antigua and Barbuda
AI     Anguilla
AL     Albania
AM     Armenia
AN     Netherlands Antilles
AO     Angola
AQ     Antarctica
AR     Argentina
AS     American Samoa
AT     Austria
AU     Australia
AW     Aruba
AX     Aland Islands
AZ     Azerbaijan
BA     Bosnia and Herzegovina
BB     Barbados
BD     Bangladesh
BE     Belgium
BF     Burkina Faso
BG     Bulgaria
BH     Bahrain
BI     Burundi
BJ     Benin
BL     Saint-Barthélemy
BM     Bermuda
BN     Brunei Darussalam
BO     Bolivia
BQ     Bonaire
BR     Brazil
BS     Bahamas
BT     Bhutan
BW     Botswana
BY     Belarus
BZ     Belize
CA     Canada
CC     Cocos (Keeling) Islands
CD     Zaire
CF     Central African Republic
CG     Congo
CH     Switzerland
CI     Côte d'Ivoire
CK     Cook Islands
CL     Chile
CM     Cameroon
CN     China
CO     Colombia
CR     Costa Rica
CU     Cuba
CV     Cape Verde
CW     Curaçao
CX     Christmas Island
CY     Cyprus
CZ     Czech Republic
DE     Germany
DJ     Djibouti
DK     Denmark
DM     Dominica
DO     Dominican Republic
DZ     Algeria
EC     Ecuador
EE     Estonia
EG     Egypt
EH     Western Sahara
ER     Eritrea
ES     Spain
ET     Ethiopia
FI     Finland
FJ     Fiji
FK     Falkland Islands
FM     Micronesia
FO     Faroe Islands
FR     France
GA     Gabon
GD     Grenada
GE     Georgia
GF     French Guiana
GG     Guernsey
GH     Ghana
GI     Gibraltar
GL     Greenland
GM     Gambia
GN     Guinea
GP     Guadeloupe
GQ     Equatorial Guinea
GR     Greece
GS     South Georgia and the South Sandwich Islands
GT     Guatemala
GU     Guam
GW     Guinea-Bissau
GY     Guyana
HK     Hong Kong
HN     Honduras
HR     Croatia
HT     Haiti
HU     Hungary
ID     Indonesia
IE     Ireland
IL     Israel
IM     Isle of Man
IN     India
IO     British Indian Ocean Territory
IQ     Iraq
IR     Iran
IS     Iceland
IT     Italy
JE     Jersey
JM     Jamaica
JO     Jordan
JP     Japan
KE     Kenya
KG     Kyrgyzstan
KH     Cambodia
KI     Kiribati
KM     Comoros
KN     Saint Kitts and Nevis
KP     North Korea
KR     South Korea
KS     Kosovo
KW     Kuwait
KY     Cayman Islands
KZ     Kazakhstan
LA     Lao PDR
LB     Lebanon
LC     Saint Lucia
LI     Liechtenstein
LK     Sri Lanka
LR     Liberia
LS     Lesotho
LT     Lithuania
LU     Luxembourg
LV     Latvia
LY     Libya
MA     Morocco
MC     Monaco
MD     Moldova
ME     Montenegro
MF     Saint-Martin
MG     Madagascar
MH     Marshall Islands
MK     Macedonia
ML     Mali
MM     Myanmar
MN     Mongolia
MO     Macao
MP     Northern Mariana Islands
MQ     Martinique
MR     Mauritania
MS     Montserrat
MT     Malta
MU     Mauritius
MV     Maldives
MW     Malawi
MX     Mexico
MY     Malaysia
MZ     Mozambique
NA     Namibia
NC     New Caledonia
NE     Niger
NF     Norfolk Island
NG     Nigeria
NI     Nicaragua
NL     Netherlands
NO     Norway
NP     Nepal
NR     Nauru
NU     Niue
NZ     New Zealand
OM     Oman
PA     Panama
PE     Peru
PF     French Polynesia
PG     Papua New Guinea
PH     Philippines
PK     Pakistan
PL     Poland
PM     Saint Pierre and Miquelon
PN     Pitcairn
PR     Puerto Rico
PS     Palestinian Territory
PT     Portugal
PW     Palau
PY     Paraguay
QA     Qatar
RE     Réunion
RO     Romania
RS     Serbia
RU     Russian Federation
RW     Rwanda
SA     Saudi Arabia
SB     Solomon Islands
SC     Seychelles
SD     Sudan
SE     Sweden
SG     Singapore
SH     Saint Helena
SI     Slovenia
SJ     Svalbard and Jan Mayen Islands
SK     Slovakia
SL     Sierra Leone
SM     San Marino
SN     Senegal
SO     Somalia
SR     Suriname
SS     South Sudan
ST     Sao Tome and Principe
SV     El Salvador
SX     Saint-Martin
SY     Syria
SZ     Swaziland
TC     Turks and Caicos Islands
TD     Chad
TF     French Southern Territories
TG     Togo
TH     Thailand
TJ     Tajikistan
TK     Tokelau
TL     Timor-Leste
TM     Turkmenistan
TN     Tunisia
TO     Tonga
TR     Turkey
TT     Trinidad and Tobago
TV     Tuvalu
TW     Taiwan
TZ     Tanzania
UA     Ukraine
UG     Uganda
UK     United Kingdom
UM     United States Minor Outlying Islands
US     United States of America
UY     Uruguay
UZ     Uzbekistan
VA     Vatican
VC     Saint Vincent and Grenadines
VE     Venezuela
VG     British Virgin Islands
VI     Virgin Islands, US
VN     Viet Nam
VU     Vanuatu
WF     Wallis and Futuna Islands
WS     Samoa
YE     Yemen
YT     Mayotte
ZA     South Africa
ZM     Zambia
ZW     Zimbabwe

citybias A string containing city names separated by commas. This is an optional parameter to bias geocoding / geoparsing results to specific cities. (to be used in conjunction with region biasing for best results)
geoit The output type desired. Only one of two allowed values: XML or CSV
json Output in JSON format. Optionally you may request data in JSON format. Accepted value: 1
geojson Output in GeoJSON format. Optionally you may request data in GeoJSON format. Accepted value: 1
jsonp Output in JSONP format. Optionally you may request data in JSONP format. Accepted value: 1
callback Callback string if Output is in JSONP format. Optionally you may request data in JSONP format. The callback can be any string value and is required if you request JSONp output.
id optionally you can include your own transaction id. this will be returned along with the response if provided. a number or string no longer that 15 bytes.
strictmode Optionally you can prevent the geocoder from making too many guesses on your input. This is now the default, but you may disable it with nostrict Allowed values are Integer 0 or 1.
nostrict Set promiscuous mode on. Will return all matched locations, even those with low confidence. (might result in a lot of matched items in geoparsing mode) Allowed values are Integer 0 or 1.
moreinfo If a search reveals more than one identical city name within the same country (for Example: Springfield, US), the top city will be returned by default (the city with the largest number of addresses). To view the other matches, pass the moreinfo parameter. Allowed values are Integer 0 or 1.

Geocoding and/or Geoparsing Responses Geocoding/Geoparsing responses are returned in the format indicated by the output flag within the URL request's path.

The output may contain the following parameters:

Parameter Name DescriptionExpected Output Values
latt The latitude. A decimal number.
longt The longitude. A decimal number.
id Transaction id. If supplied in the input the transaction id will be returned along with the output.
stnumber The properly formated address to be returned. The street number (integer value).
staddress The properly formated address to be returned. The formated street address.
city The properly formated address to be returned. The city name.
prov The properly formated address to be returned. The country code.
countryname The properly formated address to be returned. The country name.
confidence The Geocoding Confidence Score is a number representing our accuracy estimate on a geocoding request. This number ranges from 1 to 0. A higher score indicates a closer match (A score of 1 meaning best match accuracy.) A result with confidence score less than 0.5 is never returned to the user (it will most likely result in a suggestion being returned.) a number [0..1] 1=best match, 0=no response.
MentionIndices In a Geoparsing response indicates the index location in the string where a given location was matched. One or more numbers, separated by commas.
matchtype In a Geoparsing response indicates the type of location matched. Possible values {street, intersection, locality, landmark, postcode}
inlatt The input latitude. If the input contains a latitude/longitude pair for reverse geocoding.
inlongt The input longitude. If the input contains a latitude/longitude pair for reverse geocoding.
distance The distance of the result location from the input location.
NearRoad The nearest Road to the input point.
NearRoadDistance The distance of the nearest Road to the input point.

Error Codes The output could contain an error code. If your query does not produce coordinates the latt and longt containers will be empty.
These are the error codes that could be returned upon an unsuccessful lookup:

005 Postal Code is not in the proper Format.

007 Supply a valid query.

008 Your request did not produce any results. Check your spelling and try again.

Sometimes when a location is not found a suggestion (or more) will be contained within <suggestion> xml tags. for example:

Batch Geocoding Example

Bash one liner for batch geocoding CSV/Text files using the geocode.xyz CSV API Here is a bash one liner that takes as input a CSV file of locations, and outputs the file with the location information appended at the end of each line:
#!/bin/bash
while IFS='' read -r line || [[ -n "$line" ]]; do
    echo $line,`curl -X POST -d locate="$line" -d geoit="csv" https://geocode.xyz`;
done < "$1"
Save as geocode.sh then chmod a+x geocode.sh then run it as:
./geocode.sh input.csv>output.csv

Your input file might look something like:
input.csv

Berlin, DE
London, UK
Rome, IT
and the output

output.csv

Berlin, DE,200,0.90,52.50219,13.40741
London, UK,200,0.90,51.50565,-0.11599
Rome, IT,200,0.80,41.94176,12.61489
Four columns were appended to the input file. The status (200 success), the confidence score (a number between 0 and 1, with 1 being best match), the Latitude and the Longitude.



- (optional)

About Geocode.xyz

This API provides worldwide forward/reverse geocoding, batch geocoding and geoparsing.
Read our API docs for more.

Geoparsing and Geocoding and Batch Geocoding Examples

Forward and Reverse Geocoding
  1. Museumplein, Amsterdam
  2. 2 Colomines, Barcelona, ES
  3. Antoine Dansaertstraat, Brussels
  4. Karlsplatz, Vienna
  5. Nyhavn, Copenhagen
  6. 55.6802779000,12.5900501000
  7. B72 1JU

Geoparsing News Feeds.

Geoparse & Geocode .

for more information

North America

geocode.xyz © 2017. Legal

Our Clients: