Country Lookup

Determine which country a GPS coordinate falls in.

Endpoint

GET /geo/country/fromGps/{latitude},{longitude}

Parameters

Parameter	Type	Location	Description
latitude	number	path	Latitude coordinate (-90 to 90)
longitude	number	path	Longitude coordinate (-180 to 180)

Response

Returns an ISO 3166-1 alpha-3 country code as a plain string.

Examples

# New York, USA
curl "https://api.boxesnlines.com/geo/country/fromGps/40.7128,-74.0060" \
  -H "X-API-Key: YOUR_API_KEY"
# Response: "USA"

# London, UK
curl "https://api.boxesnlines.com/geo/country/fromGps/51.5074,-0.1278" \
  -H "X-API-Key: YOUR_API_KEY"
# Response: "GBR"

# Tokyo, Japan
curl "https://api.boxesnlines.com/geo/country/fromGps/35.6762,139.6503" \
  -H "X-API-Key: YOUR_API_KEY"
# Response: "JPN"

const response = await fetch(
  "https://api.boxesnlines.com/geo/country/fromGps/40.7128,-74.0060",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

const countryCode = await response.text();
console.log(countryCode); // "USA"

Error Responses

Status	Description
400	Invalid coordinates (latitude outside -90 to 90, longitude outside -180 to 180)
404	No country found at the given coordinates (e.g., ocean, Antarctica)
429	Rate limit exceeded

For detailed error handling patterns, see Error Handling.

Use Cases

• User localization: Detect a user's country for language or currency defaults
• Content filtering: Show region-specific content based on location
• Analytics: Aggregate user activity by country
• Compliance: Verify user location for regulatory requirements

Related

• Subdivision Lookup -get the subdivision-level code for finer granularity
• Point-in-Area Check -verify if coordinates fall within a specific country using isInCountry
• Rate Limits -understand rate limit headers and quotas

Try It

Use the interactive API reference to test this endpoint with your own API key.