Geocode.xyz — API Integration Examples

Quick start (curl)

Replace YOUR_API_KEY. JSON uses json=1. XML/CSV uses geoit=xml or geoit=csv.

CLI

Reverse (lat,lon → nearest address)

curl 'https://geocode.xyz/51.50354,-0.12768?geoit=xml&auth=YOUR_API_KEY'

Forward (address → lat,lon)

curl 'https://geocode.xyz/Hauptstr.,+57632+Berzhausen?json=1&auth=YOUR_API_KEY'

Geoparse (text → many places)

curl -X POST \
  -d scantext="The most important museums of Amsterdam are located on the Museumplein..." \
  -d geojson=1 \
  -d auth=YOUR_API_KEY \
  https://geocode.xyz

Tip: for long input strings, use the parameterized form with locate (GET or POST) to avoid “file name too long”.

Core request shapes

Two common URL patterns for geocoding, plus scantext for geoparsing.

Reference

1) “Path” style

https://geocode.xyz/{location}?{outputformat}&auth=YOUR_API_KEY

Forward: address/city/landmark. Reverse: lat,lon.

2) Parameter style (recommended for long strings)

https://geocode.xyz/?locate={location}&{outputformat}&auth=YOUR_API_KEY

3) Geoparsing

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

Output: json=1, geojson=1, geoit=xml/geoit=csv, JSONP via callback=fn.

Forward geocoding (address → lat,lon)

Pass an address-like string as the “location”. Use locate= to avoid path-length issues.

Many languages

HTTPie

http GET 'https://geocode.xyz/' \
  locate=='1600 Amphitheatre Parkway, Mountain View, CA' \
  json==1 auth==YOUR_API_KEY

wget

wget -qO- "https://geocode.xyz/?locate=Hauptstr.,+57632+Berzhausen&json=1&auth=YOUR_API_KEY"

PowerShell

$u = "https://geocode.xyz/?locate=Hauptstr.,+57632+Berzhausen&json=1&auth=YOUR_API_KEY"
Invoke-RestMethod -Uri $u -Method GET

Bash + jq

curl -sG "https://geocode.xyz/" \
  --data-urlencode "locate=10 Downing St, London" \
  --data "json=1" \
  --data "auth=YOUR_API_KEY" \
| jq -r '.latt + "," + .longt'

Python (requests)

import requests

params = {
  "locate": "Hauptstr., 57632 Berzhausen",
  "json": "1",
  "auth": "YOUR_API_KEY",
}
r = requests.get("https://geocode.xyz/", params=params, timeout=20)
r.raise_for_status()
data = r.json()
print(data.get("latt"), data.get("longt"))

Node.js (fetch)

const params = new URLSearchParams({
  locate: "Hauptstr., 57632 Berzhausen",
  json: "1",
  auth: "YOUR_API_KEY",
});

const res = await fetch("https://geocode.xyz/?" + params.toString());
if (!res.ok) throw new Error(await res.text());
const data = await res.json();
console.log(data.latt, data.longt);

PHP (cURL)

<?php
$q = http_build_query([
  "locate" => "Hauptstr., 57632 Berzhausen",
  "json"   => "1",
  "auth"   => "YOUR_API_KEY",
]);

$ch = curl_init("https://geocode.xyz/?$q");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 20,
]);
$out = curl_exec($ch);
if ($out === false) die(curl_error($ch));
curl_close($ch);

$data = json_decode($out, true);
echo $data["latt"] . "," . $data["longt"] . PHP_EOL;

Perl (HTTP::Tiny)

use strict;
use warnings;
use HTTP::Tiny;
use URI::Escape qw(uri_escape);
use JSON qw(decode_json);

my $loc = uri_escape("Hauptstr., 57632 Berzhausen");
my $url = "https://geocode.xyz/?locate=$loc&json=1&auth=YOUR_API_KEY";

my $http = HTTP::Tiny->new(timeout => 20);
my $res  = $http->get($url);
die "HTTP $res->{status}: $res->{reason}\n$res->{content}\n" unless $res->{success};

my $data = decode_json($res->{content});
print $data->{latt}, ",", $data->{longt}, "\n";

Ruby (Net::HTTP)

require "uri"
require "net/http"
require "json"

uri = URI("https://geocode.xyz/")
uri.query = URI.encode_www_form({
  locate: "Hauptstr., 57632 Berzhausen",
  json: "1",
  auth: "YOUR_API_KEY"
})

res = Net::HTTP.get_response(uri)
raise res.body unless res.is_a?(Net::HTTPSuccess)
data = JSON.parse(res.body)
puts "#{data["latt"]},#{data["longt"]}"

Go (net/http)

package main

import (
  "encoding/json"
  "fmt"
  "net/http"
  "net/url"
  "time"
)

func main() {
  params := url.Values{}
  params.Set("locate", "Hauptstr., 57632 Berzhausen")
  params.Set("json", "1")
  params.Set("auth", "YOUR_API_KEY")

  u := "https://geocode.xyz/?" + params.Encode()

  c := http.Client{Timeout: 20 * time.Second}
  resp, err := c.Get(u)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  var data map[string]any
  if err := json.NewDecoder(resp.Body).Decode(&data); err != nil { panic(err) }

  fmt.Println(data["latt"], data["longt"])
}

R (httr)

library(httr)
library(jsonlite)

res <- GET("https://geocode.xyz/",
  query=list(locate="Hauptstr., 57632 Berzhausen", json=1, auth="YOUR_API_KEY")
)
stop_for_status(res)
data <- fromJSON(content(res, "text", encoding="UTF-8"))
cat(data$latt, data$longt, "\n")

Java (HttpClient)

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;

public class Geo {
  public static void main(String[] args) throws Exception {
    String q = "locate=" + URLEncoder.encode("Hauptstr., 57632 Berzhausen", StandardCharsets.UTF_8)
      + "&json=1&auth=YOUR_API_KEY";

    HttpClient client = HttpClient.newHttpClient();
    HttpRequest req = HttpRequest.newBuilder()
      .uri(URI.create("https://geocode.xyz/?" + q))
      .GET().build();

    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}

C# (.NET HttpClient)

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
  static async Task Main() {
    var url = "https://geocode.xyz/?locate=" +
      Uri.EscapeDataString("Hauptstr., 57632 Berzhausen") +
      "&json=1&auth=YOUR_API_KEY";

    using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(20) };
    var json = await http.GetStringAsync(url);
    Console.WriteLine(json);
  }
}

Reverse geocoding (lat,lon → nearest address)

Pass coordinates as lat,lon in that order.

Examples

curl (JSON)

curl "https://geocode.xyz/55.6802779,12.5900501?json=1&auth=YOUR_API_KEY"

Python

import requests
lat, lon = 55.6802779, 12.5900501
url = f"https://geocode.xyz/{lat},{lon}"
data = requests.get(url, params={"json":"1","auth":"YOUR_API_KEY"}, timeout=20).json()
print(data.get("staddress"), data.get("city"), data.get("prov"), data.get("country"))

Node.js

const lat = 55.6802779, lon = 12.5900501;
const u = new URL(`https://geocode.xyz/${lat},${lon}`);
u.search = new URLSearchParams({ json: "1", auth: "YOUR_API_KEY" }).toString();

const res = await fetch(u);
const data = await res.json();
console.log(data.staddress, data.city, data.prov, data.country);

CSV output

curl "https://geocode.xyz/55.6802779,12.5900501?geoit=csv&auth=YOUR_API_KEY"

If you only want core reverse-geocode components, try strictmode=1. If you want more data like timezone/elevation, try moreinfo=1.

Geoparsing (text → multiple matched places)

Use scantext. POST is recommended for long text.

POST

curl (GeoJSON)

curl -X POST https://geocode.xyz \
  -d scantext="The most important museums of Amsterdam are located on the Museumplein..." \
  -d geojson=1 \
  -d auth=YOUR_API_KEY

curl (JSON + sentiment)

curl -X POST https://geocode.xyz \
  -d scantext="In the bestselling novel Crazy Rich Asians..." \
  -d geoit=json \
  -d sentiment=analysis \
  -d auth=YOUR_API_KEY

Python (POST)

import requests

payload = {
  "scantext": "The Vienna Tourist Board operates information and booking booths...",
  "json": "1",
  "auth": "YOUR_API_KEY",
}

r = requests.post("https://geocode.xyz", data=payload, timeout=30)
r.raise_for_status()
print(r.json())

Node.js (POST)

const payload = new URLSearchParams({
  scantext: "The most important museums of Amsterdam are located on the Museumplein...",
  geojson: "1",
  auth: "YOUR_API_KEY",
});

const res = await fetch("https://geocode.xyz", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: payload.toString(),
});

console.log(await res.text());

Disambiguation tip: if your data is known to be in a region/country, add region=XX (ISO code) to reduce collisions.

Output format cheatsheet

Omit output params and the default is HTML. Otherwise choose one.

Formats

json=1 → JSON geojson=1 → GeoJSON geoit=xml → XML geoit=csv → CSV callback=fn → JSONP

Example: https://geocode.xyz/41.3189957000,2.0746469000?json=1&auth=YOUR_API_KEY

Usage notes (practical)

Production integration patterns you’ll typically want.

Ops

Cache results (Redis/memory) to save cost and reduce latency.
Rate-limit outbound calls and use retries with exponential backoff on transient failures.
Normalize provider output into your own schema so you can swap providers later.
Use workers for large batches (queue + concurrency) rather than geocoding inside web requests.

Server-side patterns (proxy, worker, serverless)

Keep keys private; put your app in front of the API.

Architecture

Nginx reverse proxy (hide auth)

# /etc/nginx/conf.d/geocode.conf
server {
  listen 80;
  server_name yourdomain.com;

  location /geocode {
    proxy_set_header Host geocode.xyz;
    proxy_pass https://geocode.xyz/;
  }
}

Append &auth=YOUR_API_KEY server-side before proxying (don’t do it in browser JS).

Serverless (Cloudflare Worker style)

export default {
  async fetch(req, env) {
    const u = new URL(req.url);
    const locate = u.searchParams.get("locate");
    if (!locate) return new Response("missing locate", { status: 400 });

    const upstream = new URL("https://geocode.xyz/");
    upstream.searchParams.set("locate", locate);
    upstream.searchParams.set("json", "1");
    upstream.searchParams.set("auth", env.GEOCODE_XYZ_KEY);

    const res = await fetch(upstream.toString(), {
      headers: { "Accept": "application/json" },
    });

    return new Response(res.body, {
      status: res.status,
      headers: { "Content-Type": "application/json" },
    });
  }
}

Batch worker (bash)

# addresses.txt: one address per line
while IFS= read -r addr; do
  curl -sG "https://geocode.xyz/" \
    --data-urlencode "locate=$addr" \
    --data "json=1" \
    --data "auth=YOUR_API_KEY"
  echo
  sleep 0.12  # tune to your plan / rate limit
done < addresses.txt

Docker “one-off” test

docker run --rm curlimages/curl:8.5.0 \
  -s "https://geocode.xyz/?locate=10+Downing+St,+London&json=1&auth=YOUR_API_KEY"

Geocode.xyz API: Geocoding, Reverse Geocoding & Geoparsing