GET /v1/nearest

Overview

Snap-to-road corrects a single GPS coordinate by finding the nearest point on the road network. This is useful for fixing a GPS reading that drifted off-road due to signal issues.

Unlike map matching which processes an entire GPS trace, this endpoint handles a single point.

Coordinate Order

The /v1/nearest endpoint returns the snapped coordinate as a location: [longitude, latitude] array following the GeoJSON standard order, not as separate lat/lon fields. Read snapped.location[0] for longitude and snapped.location[1] for latitude.

info

The format query parameter (for requesting GeoJSON output) is not supported on this endpoint. The response is always JSON. Use /v1/geocode or /v1/reverse if you need GeoJSON output.

Request

GET https://api.geocodeme.net/v1/nearest

Required header: X-Api-Key: gm_YOUR_API_KEY

Parameters

Parameter	Type	Required	Default	Description
lat	float	Yes	n/a	Latitude of the GPS point (-90 to 90)
lon	float	Yes	n/a	Longitude of the GPS point (-180 to 180)
profile	string	No	car	Routing profile: car, bike, foot, truck, or moto (plan-gated)

Cost: 1 credit per request. Plan gating: car on every plan; bike/foot from Startup; truck/moto from Growth. A profile outside your plan returns 403 PLAN_UPGRADE_REQUIRED, and never consumes credits.

Code Examples

cURL

curl -H "X-Api-Key: gm_YOUR_API_KEY" \
  "https://api.geocodeme.net/v1/nearest?lat=48.8566&lon=2.3522"

Python

import os
import requests

api_key = os.environ["GEOCODEME_API_KEY"]

response = requests.get(
    "https://api.geocodeme.net/v1/nearest",
    params={"lat": 48.8566, "lon": 2.3522},
    headers={"X-Api-Key": api_key},
)
response.raise_for_status()

data = response.json()
snapped = data["snapped"]
if snapped is not None:
    print(f"Snapped to: {snapped['name']}")
    print(f"Distance from input: {snapped['distance_meters']}m")

JavaScript

const apiKey = process.env.GEOCODEME_API_KEY;

const response = await fetch(
  "https://api.geocodeme.net/v1/nearest?lat=48.8566&lon=2.3522",
  { headers: { "X-Api-Key": apiKey } }
);

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}

const data = await response.json();
if (data.snapped !== null) {
  console.log(`Snapped to: ${data.snapped.name}`);
  console.log(`Distance from input: ${data.snapped.distance_meters}m`);
}

PHP

<?php
$apiKey = getenv('GEOCODEME_API_KEY');

$url = 'https://api.geocodeme.net/v1/nearest?' . http_build_query([
    'lat' => 48.8566,
    'lon' => 2.3522,
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: $apiKey"]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    throw new \RuntimeException("HTTP $httpCode: $response");
}

$data = json_decode($response, true);
if ($data['snapped'] !== null) {
    echo "Snapped to: " . $data['snapped']['name'] . "\n";
    echo "Distance from input: " . $data['snapped']['distance_meters'] . "m\n";
}

Response

info

All responses include rate limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Monthly-Remaining, etc.).

{
  "snapped": {
    "location": [2.3519, 48.8567],
    "name": "Rue de Rivoli",
    "distance_meters": 3.2
  },
  "attribution": "Route data (c) OpenStreetMap contributors",
  "meta": {
    "took_ms": 12,
    "cache_hit": false
  }
}

Schema

Top-level response

Field	Type	Description
snapped	object | null	The snapped point, or null when no road is found nearby
attribution	string	Always "Route data (c) OpenStreetMap contributors"
meta	object	Request metadata
meta.took_ms	integer	Server processing time in milliseconds
meta.cache_hit	boolean	Whether the response was served from cache

snapped

Field	Type	Description
location	array	Snapped coordinate as [longitude, latitude]
name	string	Name of the nearest road segment (may be empty for unnamed roads)
distance_meters	float	Distance in meters from the input point to the snapped location

Error Responses

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'lat' is missing",
    "field": "lat"
  }
}

tip

All endpoints are also subject to INVALID_API_KEY (401) and RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED (429) errors. See Error Codes for the full reference.