Subdivision Lookup

Determine which province or subdivision a GPS coordinate falls in.

Endpoint

GET /geo/subdivision/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-2 subdivision code as a plain string.

Examples

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

# São Paulo, Brazil
curl "https://api.boxesnlines.com/geo/subdivision/fromGps/-23.5505,-46.6333" \
  -H "X-API-Key: YOUR_API_KEY"
# Response: "BR-SP"

# Bavaria, Germany
curl "https://api.boxesnlines.com/geo/subdivision/fromGps/48.1351,11.5820" \
  -H "X-API-Key: YOUR_API_KEY"
# Response: "DE-BY"

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

const subdivisionCode = await response.text();
console.log(subdivisionCode); // "US-NY"

Error Responses

Status	Description
400	Invalid coordinates (latitude outside -90 to 90, longitude outside -180 to 180)
404	No subdivision found at the given coordinates (ocean, disputed territory, etc.)
429	Rate limit exceeded

For detailed error handling patterns, see Error Handling.

Use Cases

• Regional compliance: Enforce subdivision-level regulations (e.g., US state privacy laws like CCPA, regional data residency requirements)
• Tax calculation: Determine the correct tax jurisdiction at the subdivision level
• Shipping zones: Route orders to the correct regional warehouse or calculate zone-based shipping rates
• Localized content: Serve region-specific content, promotions, or language variants within a country
• Service availability: Check if a service operates in a particular subdivision before accepting orders

Related

• Country Lookup -get the country-level code instead
• Point-in-Area Check -verify if coordinates fall within a specific subdivision using isInSubdivision
• Rate Limits -understand rate limit headers and quotas

Try It

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