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

App · 6 actions. Web page: https://docs.lodol.com/docs/integrations/geocode-xyz

## Actions

### 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**

- Text (`text`, text, required): The text to scan, up to 50,000 characters.
- Prefer these countries (`countries`, list): 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 confidence (`minimum_confidence`, number): 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 matches (`include_weak_matches`, true/false): Also return words that only might be places. Finds more, but more of it is wrong. Default: `false`.
- Analyse sentiment (`analyse_sentiment`, true/false): Also score the text's mood: an overall positive, negative or neutral, and a score for each emotion. Default: `false`.

**Outputs**

- `count` (number): How many places were found
- `places` (list): The places found, most confident first
- `sentiment` (object): The text's mood, when asked for
- `summary` (text): The result as a sentence, ready to put in a message

**Example output**

```json
{
  "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**

- Latitude (`latitude`, number, required): Latitude of the point, from -90 to 90. From -90 to 90.
- Longitude (`longitude`, number, required): Longitude of the point, from -180 to 180. Places in the Americas take a negative longitude. From -180 to 180.
- Include nearby addresses and areas (`include_area_details`, true/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**

- `address` (object): The address split into its parts. Empty when nothing was found.
- `admin_areas` (list): The areas the point lies in, largest first, when asked for
- `area_tags` (object): OpenStreetMap tags of the smallest area, when asked for
- `confidence` (number): How sure Geocode.xyz is, from 0 to 1
- `distance_km` (number): How far the address is from the point, in km
- `elevation_m` (number): Height above sea level, in metres
- `formatted_address` (text): The address on one line
- `found` (true/false): Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
- `geocode` (text): Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
- `geonumber` (text): The number of the 10 m square the spot lies in
- `latitude` (number): Latitude of the address found
- `longitude` (number): Longitude of the address found
- `nearby_addresses` (list): Other addresses close by, when asked for
- `nearest_intersection` (object): The closest junction of two streets
- `query_latitude` (number): The latitude that was looked up
- `query_longitude` (number): The longitude that was looked up
- `road_class` (text): The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
- `summary` (text): The result as a sentence, ready to put in a message
- `timezone` (text): IANA time zone, such as Europe/London

**Example output**

```json
{
  "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 place (`address`, text, required): 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 countries (`countries`, list): 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 cities (`prefer_cities`, text): 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 elevation (`include_timezone_and_elevation`, true/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 confidence (`minimum_confidence`, number): 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**

- `address` (object): The address split into its parts. Empty when nothing was found.
- `alternatives` (list): Other places the address could mean
- `confidence` (number): How sure Geocode.xyz is, from 0 to 1
- `elevation_m` (number): Height above sea level in metres, when asked for
- `formatted_address` (text): The matched address on one line
- `found` (true/false): Whether a match was found (and met the minimum confidence). False is an answer: branch on it.
- `geonumber` (text): The 10 m square it lies in, when asked for
- `latitude` (number): Latitude of the match
- `longitude` (number): Longitude of the match
- `query` (text): The address that was looked up
- `suggestion` (object): When nothing was found, a rewrite of the address Geocode.xyz suggests trying instead
- `summary` (text): The result as a sentence, ready to put in a message
- `timezone` (text): IANA time zone, when asked for

**Example output**

```json
{
  "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 address (`ip_address`, text, required): The IPv4 address to locate, such as 8.8.8.8.
- Include nearby addresses and areas (`include_area_details`, true/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**

- `address` (object): The address split into its parts. Empty when nothing was found.
- `admin_areas` (list): The areas the point lies in, largest first, when asked for
- `area_tags` (object): OpenStreetMap tags of the smallest area, when asked for
- `confidence` (number): How sure Geocode.xyz is, from 0 to 1
- `distance_km` (number): How far the address is from the point, in km
- `elevation_m` (number): Height above sea level, in metres
- `formatted_address` (text): The address on one line
- `found` (true/false): Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
- `geocode` (text): Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
- `geonumber` (text): The number of the 10 m square the spot lies in
- `ip_address` (text): The IP address that was looked up
- `latitude` (number): Latitude of the address found
- `longitude` (number): Longitude of the address found
- `nearby_addresses` (list): Other addresses close by, when asked for
- `nearest_intersection` (object): The closest junction of two streets
- `road_class` (text): The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
- `summary` (text): The result as a sentence, ready to put in a message
- `timezone` (text): IANA time zone, such as Europe/London

**Example output**

```json
{
  "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 geonumber (`code`, text, required): A geocode such as LONDON-MCRXA or a geonumber such as 3154700960970.
- Include nearby addresses and areas (`include_area_details`, true/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**

- `address` (object): The address split into its parts. Empty when nothing was found.
- `admin_areas` (list): The areas the point lies in, largest first, when asked for
- `area_tags` (object): OpenStreetMap tags of the smallest area, when asked for
- `code` (text): The geocode or geonumber looked up
- `confidence` (number): How sure Geocode.xyz is, from 0 to 1
- `distance_km` (number): How far the address is from the point, in km
- `elevation_m` (number): Height above sea level, in metres
- `formatted_address` (text): The address on one line
- `found` (true/false): Whether Geocode.xyz placed it. False is an answer, not a failure: branch on it.
- `geocode` (text): Geocode.xyz's short code for the spot, such as LONDON-MCRXA - what 'Look up a geocode or geonumber' takes
- `geonumber` (text): The number of the 10 m square the spot lies in
- `latitude` (number): Latitude of the address found
- `longitude` (number): Longitude of the address found
- `nearby_addresses` (list): Other addresses close by, when asked for
- `nearest_intersection` (object): The closest junction of two streets
- `road_class` (text): The nearest road's speed limit in km/h, or its type such as footway, when Geocode.xyz knows it
- `summary` (text): The result as a sentence, ready to put in a message
- `timezone` (text): IANA time zone, such as Europe/London

**Example output**

```json
{
  "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**

- Country (`country`, text, required): 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 far (`street`, text, required): The start of the street name, or a postcode.
- City so far (`city`, text): The start of the city name, to narrow the list.

**Outputs**

- `best_match` (text): The likeliest street and city on one line, ready for 'Geocode an address'
- `count` (number): How many suggestions came back
- `suggestions` (list): Matching streets, likeliest first
- `summary` (text): The result as a sentence, ready to put in a message

**Example output**

```json
{
  "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."
}
```