GET

Coordinates Lookup API

Turn a free-text place name — a city, neighborhood, landmark, or airport — into geographic coordinates you can use anywhere.

Overview

Primary Use Case

Resolve a place name to latitude/longitude, then feed those coordinates into any of StayAPI's location-based endpoints (for example, searching for hotels or restaurants near a location).

Many StayAPI endpoints search by latitude and longitude. This endpoint is the bridge: give it a place name and it returns the resolved location with coordinates, a place type, and a country code.

Endpoint URL

GET https://api.stayapi.com/v1/meta/coordinates-lookup

Parameters

Parameter	Type	Required	Description
term	string	Required	The place name to resolve (e.g. `Manhattan`, `Central Park`, `Paris`). Whitespace is trimmed; an empty value returns a 400.
limit	integer	Optional	Maximum number of locations to return (1–25, default 10). The lookup typically resolves to a single best match.

Response Format

Success Response (200 OK)

Field	Type	Description
success	boolean	Always `true` on a 2xx response
query	string	The (trimmed) term you searched
total	integer	Number of locations returned (`0` if nothing matched)
locations	array	List of matching locations (see fields below)

Location Object

Field	Type	Description
name	string	Full formatted address / label of the place
type	string	Place type — e.g. `locality`, `country`, `airport`, `point_of_interest`
latitude	number	Latitude of the location
longitude	number	Longitude of the location
country	string	ISO 3166-1 alpha-2 country code (may be `null`)
place_id	string	Stable identifier for the location

No matches

A valid query that matches nothing is still a success: you get HTTP 200 with "total": 0 and an empty "locations" array — not an error.

Common Use Cases

Powering Location Search

Let users type a city or neighborhood, resolve it to coordinates, then search hotels or restaurants near that point.

Name in, coordinates out

Map Centering

Center a map on a searched place using the returned latitude and longitude.

Instant map focus

Data Enrichment

Attach coordinates and a country code to place names in your own database.

Normalize your data

Autosuggest Backends

Resolve a selected suggestion to coordinates before running a geo query.

Bridge UI to search

Error Responses

Errors follow the RFC 7807 Problem Details format.

400 Bad Request

The term parameter is missing or empty.

{
  "type": "https://api.stayapi.com/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Parameter 'term' must not be empty.",
  "error_code": "INVALID_INPUT"
}

502 Upstream Error

The lookup provider was temporarily unavailable. Retry after a short delay.

{
  "type": "https://api.stayapi.com/errors/upstream-error",
  "title": "Upstream Error",
  "status": 502,
  "detail": "Failed to resolve the location",
  "error_code": "UPSTREAM_ERROR"
}

Request

curl -X GET "https://api.stayapi.com/v1/meta/coordinates-lookup?term=Manhattan" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch("https://api.stayapi.com/v1/meta/coordinates-lookup?" +
  new URLSearchParams({ term: "Manhattan" }), {
  headers: { "x-api-key": "YOUR_API_KEY" }
});

const data = await response.json();
const place = data.locations[0];
console.log(`${place.name}: ${place.latitude}, ${place.longitude}`);

import requests

url = "https://api.stayapi.com/v1/meta/coordinates-lookup"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {"term": "Manhattan"}

response = requests.get(url, headers=headers, params=params)
data = response.json()

if response.status_code == 200 and data["total"] > 0:
    place = data["locations"][0]
    print(f"{place[\"name\"]}: {place[\"latitude\"]}, {place[\"longitude\"]}")
else:
    print(f"No match (status {response.status_code})")

<?php
$url = "https://api.stayapi.com/v1/meta/coordinates-lookup?" . http_build_query([
    "term" => "Manhattan"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($data["locations"])) {
    $place = $data["locations"][0];
    echo $place["name"] . ": " . $place["latitude"] . ", " . $place["longitude"] . "\n";
}
?>

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

uri = URI("https://api.stayapi.com/v1/meta/coordinates-lookup")
uri.query = URI.encode_www_form(term: "Manhattan")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request["x-api-key"] = "YOUR_API_KEY"

response = http.request(request)
data = JSON.parse(response.body)

if response.code == "200" && data["total"] > 0
  place = data["locations"].first
  puts "#{place["name"]}: #{place["latitude"]}, #{place["longitude"]}"
end

Response

{
  "success": true,
  "query": "manhattan",
  "total": 1,
  "locations": [
    {
      "name": "Manhattan, New York, NY, USA",
      "type": "sublocality",
      "latitude": 40.7685167,
      "longitude": -73.9821938,
      "country": "US",
      "place_id": "ChIJYeZuBI9YwokRjMDs_IEyCwo"
    }
  ]
}

{
  "type": "https://api.stayapi.com/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Parameter 'term' must not be empty.",
  "error_code": "INVALID_INPUT"
}