Location API Documentation

The Proximitii Location API turns a latitude and longitude in the United States or Canada into a readable place. It returns the country, state or province, city, neighborhood, nearby locality and road, and a named street intersection when available.

Use it to label map pins, listings and search results without asking visitors to enter a place name. The response is based on available geographic data, not an exact street address. Some fields can be null when no suitable feature is found. Country is inferred from the coordinates; no country or radius parameter is needed.

Displaying this API's data on a public page? Show the Powered by Proximitii logo directly below it. See API Attribution.

Example Calls

GET https://api.proximitii.com/v1/location/

Send lat and lon with your public and private API keys. Call the endpoint from your server so the private key stays hidden. These examples use a coordinate in Chicago.

Node.js (server-side)

const params = new URLSearchParams({
  lat: '41.8781',
  lon: '-87.6298'
});

const response = await fetch(
  'https://api.proximitii.com/v1/location/?' + params,
  {
    headers: {
      'Public-Key': process.env.PROXIMITII_PUBLIC_KEY,
      'Private-Key': process.env.PROXIMITII_PRIVATE_KEY
    }
  }
);

const result = await response.json();
if (!response.ok) throw new Error(result.status?.message || 'Location request failed');
console.log(result.data);

PHP (server-side)

<?php
$params = http_build_query([
    'lat' => '41.8781',
    'lon' => '-87.6298'
]);
$ch = curl_init('https://api.proximitii.com/v1/location/?' . $params);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Public-Key: ' . getenv('PROXIMITII_PUBLIC_KEY'),
        'Private-Key: ' . getenv('PROXIMITII_PRIVATE_KEY')
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15
]);
$body = curl_exec($ch);
if ($body === false) {
    $error = curl_error($ch);
    curl_close($ch);
    throw new RuntimeException($error);
}
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($httpStatus !== 200) {
    throw new RuntimeException($result['status']['message'] ?? 'Location request failed');
}
print_r($result['data']);

The endpoint also accepts a JSON POST body with lat and lon. A successful request returns HTTP 200 with data and status objects.

Response Codes

Check both the HTTP status and the response's status object. Error responses may include a request_id for support.

Code	Meaning
200 OK	Location data returned.
400 Bad Request	Coordinates are missing, invalid or outside the accepted range, or the JSON body is invalid.
401 Unauthorized	The API keys could not be authenticated.
403 Forbidden	The key is inactive or the request domain is not authorized.
404 No location data	No supported US or Canadian city, state or province shape contains the coordinate.
405 Method Not Allowed	Use GET or POST. OPTIONS is available for preflight requests.
429 Too Many Requests	The rate limit was reached. Follow the `Retry-After` header before retrying.
500 Internal Server Error	The request could not be processed because of an application error.
503 Service Unavailable	A required service is temporarily unavailable. Retry later.

Keys

Use your Proximitii public and private API keys in the Public-Key and Private-Key request headers. Store the private key on your server; do not put it in browser JavaScript, URLs or a public repository.

Values

Name	Description	Accepted Values	Variable
Latitude	Latitude of the location (required).	Decimal from -90 to 90	`lat`
Longitude	Longitude of the location (required).	Decimal from -180 to 180	`lon`

Coordinates use decimal degrees. This API does not take country, radius or munit.

Response Fields

These fields appear inside data. Nearby features depend on mapped place and road data, so names and distances may change as that data is updated.

Field	Description
`country_code`	`US` or `CA`.
`city`	Containing city or municipal place, or `null` outside a mapped city shape.
`state_province`	Two-letter state, province or territory code.
`state_province_name`	Full state, province or territory name.
`display_label`	Readable label assembled from available neighborhood or locality, city, region and country.
`neighborhood`	Containing or nearby named neighborhood, quarter or suburb, when available.
`nearest_locality`	Matched city, or a containing or nearby city, town, village or hamlet when a city is unavailable.
`nearest_locality_type`	Place type for `nearest_locality`, such as `city` or `town`.
`nearest_locality_distance_m`	Distance to the locality in metres; zero for a containing locality.
`nearest_locality_distance_unit`	`meters`.
`nearest_road_name`	Nearby named road, when available.
`street_intersection`	Nearby crossing of two differently named roads, joined with `&`. It is not necessarily a major intersection.
`intersection_distance_m`	Distance from the coordinate to that crossing in metres.
`intersection_distance_unit`	`meters`.

A road may be identified without a qualifying named crossing. In that case, street_intersection and intersection_distance_m can be null.

Sample Output

Illustrative US response. Values can vary as underlying geographic data changes.

{
  "data": {
    "country_code": "US",
    "city": "Chicago",
    "state_province": "IL",
    "state_province_name": "Illinois",
    "display_label": "Financial District, Chicago, Illinois, United States",
    "neighborhood": "Financial District",
    "nearest_locality": "Chicago",
    "nearest_locality_type": "city",
    "nearest_locality_distance_m": 0,
    "nearest_locality_distance_unit": "meters",
    "nearest_road_name": "South Federal Street",
    "street_intersection": "South Federal Street & West Jackson Boulevard",
    "intersection_distance_m": 8.57,
    "intersection_distance_unit": "meters"
  },
  "status": { "code": "200", "message": "OK" }
}

For a Canadian coordinate, country_code is CA and state_province contains a province or territory code. Road and intersection fields may be null.