Back to top

API Documentation

Boundary

Overview

Boundaries represent geographic areas (countries, cities, neighborhoods, postal codes) stored as GeoJSON geometries.

Clients can search for boundaries by name (autocomplete/suggestions), then use the returned GeoJSON to pass to endpoints like /valerts or draw on a map.

Search boundaries

Search boundaries
GET/boundaries/search{?q}

q (string, optional) - Search query for boundary name (e.g. “Dallas”, “90210”)

boundary_type (string, optional) - Filter by type: country, city, neighborhood, or postal_code

country (string, optional) - Filter by country code (e.g. “US”, “CA”, “MX”)

state (string, optional) - Filter by state/province name (e.g. “Texas”, “Ontario”)

limit (integer, optional) - Maximum number of results (default: 50)

start (integer, optional) - Offset for pagination (default: 0)

Example URI

GET /boundaries/search?q=Test Neighborhood
URI Parameters
HideShow
q
string (required) Example: Test Neighborhood
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "b3ce2fe0-80ca-47e6-abfa-42d9120e413b",
      "external_id": "relation/999001",
      "boundary_type": "neighborhood",
      "title": "Test Neighborhood",
      "country": "US",
      "state": "Texas",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -96.8,
              32.78
            ],
            [
              -96.79,
              32.78
            ],
            [
              -96.79,
              32.79
            ],
            [
              -96.8,
              32.79
            ],
            [
              -96.8,
              32.78
            ]
          ]
        ]
      },
      "center": {
        "type": "Point",
        "coordinates": [
          -96.795,
          32.785
        ]
      },
      "created_at": 1779368306.849059,
      "updated_at": 1779368306.849059,
      "aliases": "Test Neighborhood",
      "population": null,
      "searchable": "'neighborhood':2,4 'test':1,3 'texa':5 'us':6",
      "overridden_title": null,
      "type": "boundary",
      "subtitle": "Texas, US"
    }
  ],
  "info": {
    "count": 1,
    "total": 1
  }
}

Search by type

Search by type
GET/boundaries/search{?boundary_type}

Example URI

GET /boundaries/search?boundary_type=neighborhood
URI Parameters
HideShow
boundary_type
string (required) Example: neighborhood
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "b3ce2fe0-80ca-47e6-abfa-42d9120e413b",
      "external_id": "relation/999001",
      "boundary_type": "neighborhood",
      "title": "Test Neighborhood",
      "country": "US",
      "state": "Texas",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -96.8,
              32.78
            ],
            [
              -96.79,
              32.78
            ],
            [
              -96.79,
              32.79
            ],
            [
              -96.8,
              32.79
            ],
            [
              -96.8,
              32.78
            ]
          ]
        ]
      },
      "center": {
        "type": "Point",
        "coordinates": [
          -96.795,
          32.785
        ]
      },
      "created_at": 1779368306.849059,
      "updated_at": 1779368306.849059,
      "aliases": "Test Neighborhood",
      "population": null,
      "searchable": "'neighborhood':2,4 'test':1,3 'texa':5 'us':6",
      "overridden_title": null,
      "type": "boundary",
      "subtitle": "Texas, US"
    }
  ],
  "info": {
    "count": 1,
    "total": 1
  }
}

Search by country

Search by country
GET/boundaries/search{?country}

Example URI

GET /boundaries/search?country=US
URI Parameters
HideShow
country
string (required) Example: US
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "b3ce2fe0-80ca-47e6-abfa-42d9120e413b",
      "external_id": "relation/999001",
      "boundary_type": "neighborhood",
      "title": "Test Neighborhood",
      "country": "US",
      "state": "Texas",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              -96.8,
              32.78
            ],
            [
              -96.79,
              32.78
            ],
            [
              -96.79,
              32.79
            ],
            [
              -96.8,
              32.79
            ],
            [
              -96.8,
              32.78
            ]
          ]
        ]
      },
      "center": {
        "type": "Point",
        "coordinates": [
          -96.795,
          32.785
        ]
      },
      "created_at": 1779368306.849059,
      "updated_at": 1779368306.849059,
      "aliases": "Test Neighborhood",
      "population": null,
      "searchable": "'neighborhood':2,4 'test':1,3 'texa':5 'us':6",
      "overridden_title": null,
      "type": "boundary",
      "subtitle": "Texas, US"
    }
  ],
  "info": {
    "count": 1,
    "total": 1
  }
}

Get boundary by ID

Get boundary by ID
GET/boundaries/{id}

Returns a single boundary with full GeoJSON geometry and center point.

Example URI

GET /boundaries/b3ce2fe0-80ca-47e6-abfa-42d9120e413b
URI Parameters
HideShow
id
string (required) Example: b3ce2fe0-80ca-47e6-abfa-42d9120e413b
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "b3ce2fe0-80ca-47e6-abfa-42d9120e413b",
    "external_id": "relation/999001",
    "boundary_type": "neighborhood",
    "title": "Test Neighborhood",
    "country": "US",
    "state": "Texas",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -96.8,
            32.78
          ],
          [
            -96.79,
            32.78
          ],
          [
            -96.79,
            32.79
          ],
          [
            -96.8,
            32.79
          ],
          [
            -96.8,
            32.78
          ]
        ]
      ]
    },
    "center": {
      "type": "Point",
      "coordinates": [
        -96.795,
        32.785
      ]
    },
    "created_at": 1779368306.849059,
    "updated_at": 1779368306.849059,
    "aliases": "Test Neighborhood",
    "population": null,
    "searchable": "'neighborhood':2,4 'test':1,3 'texa':5 'us':6",
    "overridden_title": null,
    "type": "boundary",
    "subtitle": "Texas, US"
  }
}

Generated by aglio on 21 May 2026