Geocode.xyz

Turn addresses, places and postcodes into coordinates and coordinates back into street addresses, worldwide. Locate IP addresses, pick out the places a piece of text mentions, complete partial street names, and look up Geocode.xyz's own short codes for a spot. Works without an API key on the free tier, which is shared and throttled; add a key for requests of your own.

Actions

Action	What it does
Find places in text	Pick out the addresses, streets, cities and landmarks a piece of text mentions - an email, a post, a note - and get each with its coordinates, how sure Geocode.xyz is, and where in the text it was found.
Find the address at a point	Turn a latitude and longitude into the nearest street address, with how far away it is, the closest intersection, the time zone and the elevation.
Geocode an address	Turn an address, place name, postcode or landmark into a latitude and longitude, with the address split into its parts and how sure Geocode.xyz is of the match.
Locate an IP address	Find roughly where an IP address is - city, region, country, time zone and coordinates - with the street address nearest that point.
Look up a geocode or geonumber	Find the place a Geocode.xyz geocode (such as LONDON-MCRXA) or geonumber (such as 3154700960970) stands for, with its address and coordinates.
Suggest street names	Complete a partial street name or postcode within one country, optionally narrowed by the start of a city name, and get the likeliest matches first.

Find places in text

Pick out the addresses, streets, cities and landmarks a piece of text mentions - an email, a post, a note - and get each with its coordinates, how sure Geocode.xyz is, and where in the text it was found. Optionally reads the text's sentiment too.

Inputs

TexttexttextRequired: The text to scan, up to 50,000 characters.
Prefer these countriescountrieslist: Favour matches in these countries or regions. Geocode.xyz treats this as a strong preference rather than a hard limit, so check the country on the result when it matters. Leave empty to search the whole world.One or more of: Europe (All of Europe), Asia (All of Asia), Oceania (All of Oceania), LatinAmerica (All of Latin America), AF (Afghanistan), AL (Albania), DZ (Algeria), AS (American Samoa), AD (Andorra), AO (Angola), and 243 more.
Minimum confidenceminimum_confidencenumber: Ignore matches Geocode.xyz is less sure of than this, from 0 to 1, where 1 is an exact match. 0.5 drops most guesses. Leave empty to keep every match.From 0 to 1.
Include weak matchesinclude_weak_matchestrue/false: Also return words that only might be places. Finds more, but more of it is wrong.Default: false.
Analyse sentimentanalyse_sentimenttrue/false: Also score the text's mood: an overall positive, negative or neutral, and a score for each emotion.Default: false.

Outputs

countnumber: How many places were found
placeslist: The places found, most confident first
sentimentobject: The text's mood, when asked for
summarytext: The result as a sentence, ready to put in a message

Example output

{
  "count": 1,
  "places": [
    {
      "confidence": 1.0,
      "country_code": "GB",
      "latitude": 51.50354,
      "longitude": -0.12768,
      "match_type": "street",
      "name": "10, Downing Street, London, UK",
      "positions": [
        13,
        29
      ]
    }
  ],
  "sentiment": null,
  "summary": "Found 1 place in the text: 10, Downing Street, London, UK."
}

Find the address at a point

Turn a latitude and longitude into the nearest street address, with how far away it is, the closest intersection, the time zone and the elevation. A point with no address near it, out at sea, comes back with 'found' false.

Inputs

LatitudelatitudenumberRequired: Latitude of the point, from -90 to 90.From -90 to 90.
LongitudelongitudenumberRequired: Longitude of the point, from -180 to 180. Places in the Americas take a negative longitude.From -180 to 180.
Include nearby addresses and areasinclude_area_detailstrue/false: Also return the other addresses nearby and the administrative areas the point lies in - borough, county, region - with their OpenStreetMap tags. Off by default: the areas carry every name in dozens of languages, which makes the result long.Default: false.

Outputs

addressobject: The address split into its parts. Empty when nothing was found.
admin_areaslist: The areas the point lies in, largest first, when asked for
area_tagsobject: OpenStreetMap tags of the smallest area, when asked for
confidencenumber: How sure Geocode.xyz is, from 0 to 1
distance_kmnumber: How far the address is from the point, in km
elevation_mnumber: Height above sea level, in metres
formatted_addresstext: The address on one line
foundtrue/false: Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
geocodetext: Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
geonumbertext: The number of the 10 m square the spot lies in
latitudenumber: Latitude of the address found
longitudenumber: Longitude of the address found
nearby_addresseslist: Other addresses close by, when asked for
nearest_intersectionobject: The closest junction of two streets
query_latitudenumber: The latitude that was looked up
query_longitudenumber: The longitude that was looked up
road_classtext: The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
summarytext: The result as a sentence, ready to put in a message
timezonetext: IANA time zone, such as Europe/London

Example output

{
  "address": {
    "city": "New York",
    "country": "United States of America",
    "country_code": "US",
    "postal_code": "10118",
    "state": "New York",
    "street": "5th Avenue",
    "street_number": "350"
  },
  "admin_areas": [],
  "area_tags": {},
  "confidence": 0.9,
  "distance_km": 0.024,
  "elevation_m": 58.0,
  "formatted_address": "350 5th Avenue, New York, 10118, United States of America",
  "found": true,
  "geocode": "NEWYORKCITY-EKIOJ",
  "geonumber": "2222211406853",
  "latitude": 40.74818,
  "longitude": -73.98569,
  "nearby_addresses": [],
  "nearest_intersection": {
    "distance_km": 0.09,
    "latitude": 40.7491895,
    "longitude": -73.985921,
    "street_1": "34 ST W",
    "street_2": "W 34 ST"
  },
  "query_latitude": 40.7484,
  "query_longitude": -73.9857,
  "road_class": null,
  "summary": "The nearest address to 40.7484, -73.9857 is 350 5th Avenue, New York, 10118, United States of America (0.024 km away).",
  "timezone": "America/New_York"
}

Geocode an address

Turn an address, place name, postcode or landmark into a latitude and longitude, with the address split into its parts and how sure Geocode.xyz is of the match. Nothing found is reported with 'found' false rather than failing the step, so a workflow looping over a list carries on.

Inputs

Address or placeaddresstextRequired: What to find: a street address, a city, a postcode or a landmark. Include the city or country when you have it - it makes the match far more reliable.
Prefer these countriescountrieslist: Favour matches in these countries or regions. Geocode.xyz treats this as a strong preference rather than a hard limit, so check the country on the result when it matters. Leave empty to search the whole world.One or more of: Europe (All of Europe), Asia (All of Asia), Oceania (All of Oceania), LatinAmerica (All of Latin America), AF (Afghanistan), AL (Albania), DZ (Algeria), AS (American Samoa), AD (Andorra), AO (Angola), and 243 more.
Prefer these citiesprefer_citiestext: City names to favour when the address could be in more than one, separated by commas. Works best with a country chosen above.
Include time zone and elevationinclude_timezone_and_elevationtrue/false: Also return the place's time zone, its height above sea level and its geonumber, plus other places with the same name.Default: false.
Minimum confidenceminimum_confidencenumber: Ignore matches Geocode.xyz is less sure of than this, from 0 to 1, where 1 is an exact match. 0.5 drops most guesses. Leave empty to keep every match.From 0 to 1.

Outputs

addressobject: The address split into its parts. Empty when nothing was found.
alternativeslist: Other places the address could mean
confidencenumber: How sure Geocode.xyz is, from 0 to 1
elevation_mnumber: Height above sea level in metres, when asked for
formatted_addresstext: The matched address on one line
foundtrue/false: Whether a match was found (and met the minimum confidence). False is an answer: branch on it.
geonumbertext: The 10 m square it lies in, when asked for
latitudenumber: Latitude of the match
longitudenumber: Longitude of the match
querytext: The address that was looked up
suggestionobject: When nothing was found, a rewrite of the address Geocode.xyz suggests trying instead
summarytext: The result as a sentence, ready to put in a message
timezonetext: IANA time zone, when asked for

Example output

{
  "address": {
    "city": "London",
    "country": "United Kingdom",
    "country_code": "GB",
    "postal_code": "SW1A 2AA",
    "state": "England",
    "street": "Downing Street",
    "street_number": "10"
  },
  "alternatives": [],
  "confidence": 1.0,
  "elevation_m": null,
  "formatted_address": "10 Downing Street, London, England, SW1A 2AA, United Kingdom",
  "found": true,
  "geonumber": null,
  "latitude": 51.50354,
  "longitude": -0.12768,
  "query": "10 Downing Street, London",
  "suggestion": null,
  "summary": "'10 Downing Street, London' is at 51.50354, -0.12768: 10 Downing Street, London, England, SW1A 2AA, United Kingdom (confidence 1).",
  "timezone": null
}

Locate an IP address

Find roughly where an IP address is - city, region, country, time zone and coordinates - with the street address nearest that point. Treat the street as the neighbourhood, not the building. A private address such as 192.168.1.1 comes back with 'found' false, since it has no public location.

Inputs

IP addressip_addresstextRequired: The IPv4 address to locate, such as 8.8.8.8.
Include nearby addresses and areasinclude_area_detailstrue/false: Also return the other addresses nearby and the administrative areas the point lies in - borough, county, region - with their OpenStreetMap tags. Off by default: the areas carry every name in dozens of languages, which makes the result long.Default: false.

Outputs

addressobject: The address split into its parts. Empty when nothing was found.
admin_areaslist: The areas the point lies in, largest first, when asked for
area_tagsobject: OpenStreetMap tags of the smallest area, when asked for
confidencenumber: How sure Geocode.xyz is, from 0 to 1
distance_kmnumber: How far the address is from the point, in km
elevation_mnumber: Height above sea level, in metres
formatted_addresstext: The address on one line
foundtrue/false: Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
geocodetext: Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
geonumbertext: The number of the 10 m square the spot lies in
ip_addresstext: The IP address that was looked up
latitudenumber: Latitude of the address found
longitudenumber: Longitude of the address found
nearby_addresseslist: Other addresses close by, when asked for
nearest_intersectionobject: The closest junction of two streets
road_classtext: The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
summarytext: The result as a sentence, ready to put in a message
timezonetext: IANA time zone, such as Europe/London

Example output

{
  "address": {
    "city": "Tampa",
    "country": "United States of America",
    "country_code": "US",
    "postal_code": "33604",
    "state": "Florida",
    "street": "Douglas ST W",
    "street_number": "3108"
  },
  "admin_areas": [],
  "area_tags": {},
  "confidence": 0.6,
  "distance_km": 0.005,
  "elevation_m": 20.0,
  "formatted_address": "3108 Douglas ST W, Tampa, Florida, 33604, United States of America",
  "found": true,
  "geocode": "TOWN-FGKQL",
  "geonumber": "2180413114163",
  "ip_address": "8.8.8.8",
  "latitude": 27.97312,
  "longitude": -82.49375,
  "nearby_addresses": [],
  "nearest_intersection": {
    "distance_km": 0.021,
    "latitude": 27.973112,
    "longitude": -82.493589,
    "street_1": "W DOUGLAS ST",
    "street_2": "Douglas ST W"
  },
  "road_class": null,
  "summary": "8.8.8.8 is placed near 3108 Douglas ST W, Tampa, Florida, 33604, United States of America (27.97312, -82.49375).",
  "timezone": "America/New_York"
}

Look up a geocode or geonumber

Find the place a Geocode.xyz geocode (such as LONDON-MCRXA) or geonumber (such as 3154700960970) stands for, with its address and coordinates. Both come back from the other actions, and make short, stable ids for a spot to store in a spreadsheet.

Inputs

Geocode or geonumbercodetextRequired: A geocode such as LONDON-MCRXA or a geonumber such as 3154700960970.
Include nearby addresses and areasinclude_area_detailstrue/false: Also return the other addresses nearby and the administrative areas the point lies in - borough, county, region - with their OpenStreetMap tags. Off by default: the areas carry every name in dozens of languages, which makes the result long.Default: false.

Outputs

addressobject: The address split into its parts. Empty when nothing was found.
admin_areaslist: The areas the point lies in, largest first, when asked for
area_tagsobject: OpenStreetMap tags of the smallest area, when asked for
codetext: The geocode or geonumber looked up
confidencenumber: How sure Geocode.xyz is, from 0 to 1
distance_kmnumber: How far the address is from the point, in km
elevation_mnumber: Height above sea level, in metres
formatted_addresstext: The address on one line
foundtrue/false: Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
geocodetext: Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
geonumbertext: The number of the 10 m square the spot lies in
latitudenumber: Latitude of the address found
longitudenumber: Longitude of the address found
nearby_addresseslist: Other addresses close by, when asked for
nearest_intersectionobject: The closest junction of two streets
road_classtext: The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
summarytext: The result as a sentence, ready to put in a message
timezonetext: IANA time zone, such as Europe/London

Example output

{
  "address": {
    "city": "LONDON",
    "country": "United Kingdom",
    "country_code": "GB",
    "postal_code": "SW1A2AA",
    "state": "England",
    "street": "DOWNING STREET",
    "street_number": "1"
  },
  "admin_areas": [],
  "area_tags": {},
  "code": "LONDON-MCRXA",
  "confidence": 1.0,
  "distance_km": 0.005,
  "elevation_m": 20.0,
  "formatted_address": "1 DOWNING STREET, LONDON, England, SW1A2AA, United Kingdom",
  "found": true,
  "geocode": "LONDON-MCRXA",
  "geonumber": "3154700960970",
  "latitude": 51.50354,
  "longitude": -0.12768,
  "nearby_addresses": [],
  "nearest_intersection": {
    "distance_km": 0.071,
    "latitude": 51.5028582,
    "longitude": -0.1276451,
    "street_1": "KING CHARLES STREET",
    "street_2": "Downing Street"
  },
  "road_class": null,
  "summary": "LONDON-MCRXA is at 51.50354, -0.12768: 1 DOWNING STREET, LONDON, England, SW1A2AA, United Kingdom.",
  "timezone": "Europe/London"
}

Suggest street names

Complete a partial street name or postcode within one country, optionally narrowed by the start of a city name, and get the likeliest matches first. Use it to tidy up an address typed into a form before geocoding it.

Inputs

CountrycountrytextRequired: The country the street is in.One of: AF (Afghanistan), AL (Albania), DZ (Algeria), AS (American Samoa), AD (Andorra), AO (Angola), AI (Anguilla), AQ (Antarctica), AG (Antigua and Barbuda), AR (Argentina), and 239 more.
Street or postcode so farstreettextRequired: The start of the street name, or a postcode.
City so farcitytext: The start of the city name, to narrow the list.

Outputs

best_matchtext: The likeliest street and city on one line, ready for 'Geocode an address'
countnumber: How many suggestions came back
suggestionslist: Matching streets, likeliest first
summarytext: The result as a sentence, ready to put in a message

Example output

{
  "best_match": "Unter den Eichen Berlin",
  "count": 2,
  "suggestions": [
    {
      "city": "Berlin",
      "name": "Unter den Eichen",
      "postal_code": null,
      "score": 256.0
    },
    {
      "city": "Berlin",
      "name": "Unter den Linden",
      "postal_code": null,
      "score": 146.0
    }
  ],
  "summary": "2 suggestions for 'Unter den' in Germany; the best is Unter den Eichen Berlin."
}

ActionsCopy Anchor Link

Find places in textCopy Anchor Link

Inputs

Outputs

Find the address at a pointCopy Anchor Link

Inputs

Outputs

Geocode an addressCopy Anchor Link

Inputs

Outputs

Locate an IP addressCopy Anchor Link

Inputs

Outputs

Look up a geocode or geonumberCopy Anchor Link

Inputs

Outputs

Suggest street namesCopy Anchor Link

Inputs

Outputs

On this page

Actions

Find places in text

Find the address at a point

Geocode an address

Locate an IP address

Look up a geocode or geonumber

Suggest street names