Boundaries API

Parameters

Code samples

curl -H "X-API-Key: YOUR_KEY" \
  "https://geosearch.dev/v1/boundaries/6252001?simplify=0.01"

// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
boundary, _, err := client.BoundariesAPI.GetBoundary(ctx, 6252001).
    Simplify(0.01).Execute()

# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    boundary = geosearch.BoundariesApi(client).get_boundary(6252001, simplify=0.01).data

// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, BoundariesApi } from "@geosearch/client";

const api = new BoundariesApi(new Configuration({ apiKey: "YOUR_KEY" }));
const boundary = (await api.getBoundary({ geonameId: 6252001, simplify: 0.01 })).data;

# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
boundary = GeoSearch::BoundariesApi.new.get_boundary(6252001, simplify: 0.01).data

// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$boundary = (new GeoSearch\Api\BoundariesApi(null, $cfg))->getBoundary(6252001, 0.01)->getData();

Response

{
  "data": {
    "geoname_id": 6252001,
    "name": "United States",
    "type": "country",
    "geometry": {
      "type": "MultiPolygon",
      "coordinates": [
        [
          [
            [
              -124.7,
              48.4
            ],
            [
              -124.6,
              48.4
            ],
            [
              -124.6,
              48.3
            ],
            [
              -124.7,
              48.4
            ]
          ]
        ]
      ]
    },
    "simplify": null
  }
}

Errors

400 bad_request

{
  "error": {
    "code": "bad_request",
    "message": "invalid boundary geoname_id",
    "request_id": "req_abc123"
  }
}

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

403 tier_upgrade_required

{
  "error": {
    "code": "tier_upgrade_required",
    "message": "Boundary geometry is not included on your current plan. Upgrade to fetch boundary polygons.",
    "request_id": "req_abc123",
    "upgrade": {
      "upgrade_url": "https://geosearch.dev/dashboard#billing"
    }
  }
}

404 area_not_an_area

{
  "error": {
    "code": "area_not_an_area",
    "message": "The path segment must be the GeoNames id of a country or a region. The id supplied names something else — a city, for instance — or names nothing at all.",
    "request_id": "req_abc123"
  }
}

404 area_no_boundary

{
  "error": {
    "code": "area_no_boundary",
    "message": "That area exists, but we hold no boundary polygon for it yet. Coverage is strongest for countries and for first- and second-level regions; see the documentation for the current coverage map.",
    "request_id": "req_abc123"
  }
}

422 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [
      {
        "field": "simplify",
        "issue": "must not be negative; a tolerance is a distance, and PostGIS refuses a negative one"
      }
    ],
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

503 area_query_timeout

{
  "error": {
    "code": "area_query_timeout",
    "message": "Building that boundary polygon took too long to complete. This is usually temporary — please retry, or ask for a coarser polygon with a larger ?simplify= tolerance.",
    "request_id": "req_abc123"
  }
}