Developers · Data

Using the GeoJSON Format for Geolocation

Last updated 1 November 2026

This guide will help you build a working site where you can find records in a maximum distance of X kilometres from given geo point coordinates.

GeoJSON is a geospatial data interchange format based on JSON for encoding various geographic data structures. It defines several types of JSON objects and how they are combined to represent data about geographic features, properties, and spatial extents.

The following geometry types are supported:

Point [longitude, latitude]
LineString [[longitude, latitude], [longitude, latitude]]
Polygon [[[longitude, latitude], [longitude, latitude]]]
MultiPoint [[longitude, latitude], [longitude, latitude]]

Point [longitude, latitude]

{
  "type": "Point",
  "coordinates": [100.0, 0.0]
}

LineString [[longitude, latitude], [longitude, latitude]]

{
  "type": "LineString",
  "coordinates": [ [100.0, 0.0], [10.0, 10.0] ]
}

Polygon [[[longitude, latitude], [longitude, latitude]]]

{
  "type": "Polygon",
  "coordinates": [
    [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]
   ]
}

MultiPoint [[longitude, latitude], [longitude, latitude]]

{
  "type": "MultiPoint",
  "coordinates": [ [100.0, 0.0], [10.0, 10.0] ]
}

Read the official GeoJSON documentation to learn more.

Prerequisites

To understand this tutorial, you must have a good grasp of Database Tables, Database Items, Data Import/Export, and Forms.

Steps

Using the GeoJSON format to find all records at a maximum distance from geopoint coordinates is a four-step process:

Step 1: Create a database table
Step 2: Import data using GraphQL mutation
Step 3: Prepare GraphQL query
Step 4: Create a page

Step 1: Create a database table

Create :

name: company
properties:
  - name: name
    type: string
  - name: timezone
    type: string
  - name: city
    type: string
  - name: location
    type: geojson

Step 2: Import data using GraphQL mutation

Create a GraphQL mutation :

mutation createCompany($location: JSONPayload, $city: String, $timezone: String, $name: String){
  record_create(
    record: {
      table: "company"
      properties: [
        { name: "name" value: $name }
        { name: "city" value: $city }
        { name: "timezone" value: $timezone }
        { name: "location" value_json: $location }
      ]
    }
  ) {
    id
  }
}

Create a :

{
  "name": "Company Name",
    "city": "Boston",
    "timezone": "Timezone",
    "location": {
      "type": "Point",
      "coordinates": [-111.89903, 33.50921]
  }
}

Alternatively, you can create the record using a Form:

---
name: create_company
fields:
  properties:
    name:
      validation: { presence: true }
    city:
      validation: { presence: true }
    timezone:
      validation: { presence: true }
    location:
      validation: { geometry: true }

The HTML field snippet for geometry JSON is just a TextArea:

<div class="form-group">
  <label for="location">Location</label>
  <textarea required="true" id="location" class="form-control" name="{{ form.fields.properties.location.name }}">
  </textarea>
</div>

Note

This example is for presentation only. In a real-world scenario, no one provides raw JSON as a location address — there would be a JavaScript function using external geolocation services for getting coordinates, which then builds the required GeometryJSON structure.

Step 3: Prepare GraphQL query

Create the GraphQL query :

query search($point: GeometryJSON, $distance: Float) {
  companies: records(
    per_page: 20
    filter: {
      table: { value: "company" }
      properties: [
        {
          name: "location",
          distance_sphere: {
            center: $point,
            distance_in_km: $distance
          }
        }
      ]
    }) {
    results {
      properties
    }
  }
}

Step 4: Create a page

To wrap it up, create a page.

app/views/pages/search.liquid

{% assign location = { "type": "Point", "coordinates": [-111.89903, 33.50921] } %}
{% assign distance = context.params.distance | default: 100 | plus: 0 %}

{% graphql g = "search", point: location, distance: distance %}

{% for company in g.companies.results %}
[...]
{% endfor %}

Note

The argument is a number, and is a string, so you must turn the value into a number. You can do this by appending a plus filter with a argument - adding a 0 converts a string into a number.