Somewhere between a spreadsheet of coordinates and a working map sits a file format, and on the modern web that format is almost always GeoJSON. It is how map data travels: from databases to browsers, from field apps to newsroom graphics, from your hiking export to the map on this page. The happy news is that GeoJSON is not code in any frightening sense. It is plain text, structured like a labeled list, readable by a human and writable by hand. This article builds your first complete GeoJSON file with you, line by line, for a real place, and teaches the single rule whose violation causes nearly every GeoJSON failure ever suffered: inside GeoJSON, longitude comes first.
You need nothing installed. A text editor and this article are the whole workshop, and the explorer on this page will supply real coordinates for the file you build after the example.
Interactive map
Coordinate Explorer: Harvest Coordinates for Your First GeoJSON File
Click any place that matters to you and copy its decimal coordinates. Then build your file the way this article builds the Statue of Liberty's, remembering the one rule: longitude first.
Decimal degrees40.689167, -74.044444
Latitude40.689167° N
Longitude74.044444° W
Degrees minutes seconds40° 41' 21.00" N, 74° 02' 40.00" W
Degrees decimal minutes40° 41.350' N, 74° 02.667' W
Every coordinate in GeoJSON is written as [longitude, latitude]. East-west first, north-south second. This is the reverse of the order your phone, Google Maps, and everyday speech use, and it is the source of endless confusion, so let us be clear about why it is not a mistake. GeoJSON thinks like mathematics: a point is (x, y), horizontal then vertical, and longitude is the horizontal axis. The standard that defines GeoJSON, RFC 7946, published in 2016, fixes this order absolutely, along with the coordinate system: GeoJSON is always WGS 84, the same datum your GPS uses, with no exceptions to declare. Learn the rule once and GeoJSON holds no further surprises of that size: whenever a GeoJSON file plots your point in the ocean off Somalia or in the middle of China, the pair is swapped, and the fix is to reverse every pair in the file.
A Complete, Valid File: The Statue of Liberty
Here is an entire working GeoJSON document. It describes one point, with a name attached. Copy it into a text file, save it as liberty.geojson, and it will open in any GeoJSON viewer, in QGIS, or on geojson.io, showing a pin on the Statue of Liberty.
```json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [-74.044444, 40.689167]
},
"properties": {
"name": "Statue of Liberty",
"city": "New York"
}
}
]
}
```
Read it as nested labeled boxes. The outer box is a FeatureCollection, a set of features. Inside sits one Feature, which is GeoJSON's unit of meaning: one real-world thing. The feature has two halves. Its geometry says where it is: a Point at the coordinates [-74.044444, 40.689167], longitude first, which you can verify against every other article on this site that has used the statue's position. Its properties say what it is: any labels you like, name, city, opening hours, the color you want it drawn, in whatever words suit your project. That separation, geometry for where, properties for what, is the whole architecture of GeoJSON. Everything else is variations in the geometry.
The Seven Geometry Types
Type
What it draws
Example use
Point
One location
A statue, a well, a trailhead
MultiPoint
Several separate locations
All the benches in a park
LineString
An open path
A trail, a river, a route
MultiLineString
Several paths
A river system
Polygon
A filled area with a boundary
A lake, a park, a district
MultiPolygon
Several areas
A country with islands
GeometryCollection
A mixed bundle
Rare; a project-specific grab bag
A LineString is just a list of pairs, the path through them in order. A route from Times Square to the south end of Central Park is honestly this small:
```json
{
"type": "LineString",
"coordinates": [
[-73.9855, 40.7580],
[-73.9665, 40.7812]
]
}
```
A Polygon is a list of rings, each ring a list of pairs that returns to its starting pair to close the loop. RFC 7946 asks that outer rings wind counterclockwise and holes clockwise, the right-hand rule; most tools forgive violations, but writing them correctly costs nothing. Note the closing pair repeated at the end of a ring: an unclosed ring is the second most common GeoJSON error, right behind swapped pairs.
A woman engineer focuses on software analysis on a laptop
The Ocean Test: Diagnosing a File That Plots Wrong
When your file opens and the map shows empty water, run this diagnosis before touching anything else. Take one pair from the file and ask: is the first number plausible as a longitude and the second as a latitude for your place? For New York, longitude is about -74 and latitude about 41. If your file says [40.689167, -74.044444], the numbers are individually right and jointly swapped, and -74 is an impossible latitude for a city (latitudes stop at 90, and -74 would be deep in the Southern Ocean, which is exactly where your pin went). Reverse every pair and re-open. If the numbers are right and the order is right but the pin is still wrong, check the second classic: a sign error, a missing minus that moved the point across the equator or the prime meridian. Between swaps and signs, you have covered the overwhelming majority of GeoJSON failures, in the field and in professional shops alike.
Making Your Own First File
Build yours the way the example was built. First, get a real coordinate pair: use the explorer on this page, click a place that matters to you, and read its decimal coordinates. Second, copy the Liberty document above and replace the pair, remembering to write longitude first, and replace the properties with your own words. Third, save with the .geojson ending and open it in a viewer to watch your point appear. That loop, click, copy, swap, open, is the entire beginner workflow, and every professional pipeline is this loop wearing machinery. If you are coming from a spreadsheet of many places, know that tools exist to convert CSV to GeoJSON in bulk, and QGIS (see our qgis tutorial for beginners) imports and exports GeoJSON natively; the format also sits underneath the data in projects like openstreetmap osm exports. But the hand-built first file matters: a format you have written by hand is a format you can debug forever.
GeoJSON in the Wild: Files You Have Already Met
You have likely downloaded GeoJSON without knowing its name. Fitness apps export your recorded runs in formats that convert trivially to it, and many offer it directly. City open-data portals publish their bus stops, bike lanes, and flood zones as GeoJSON because any citizen can open it in a browser and see it, no software license required. News sites load it live: the election map shading districts and the weather map outlining a storm warning are, very often, GeoJSON files fetched as the page loads, their properties carrying the vote counts and wind speeds the colors encode. Earthquake feeds from geological surveys are GeoJSON, one feature per quake, properties holding magnitude and depth. Recognizing the format in the wild changes how you see the web's maps: behind most of them sits a small, honest text file you now know how to read, write, and repair.
One practical consequence follows. When a site offers a dataset download and the format menu includes GeoJSON among strangers like Shapefile and KML, choose GeoJSON unless a specific tool demands otherwise. It is the format that opens everywhere, converts to everything else without loss, and never requires a license, a plugin, or a prayer.
Related Guides
Readers working through this topic usually need its closest companions too. These GIS and open map data guides cover the neighboring ground:
Carrying geographic data between programs in a form both humans and machines can read. Web maps load it to draw points and boundaries, newsrooms use it for election and weather maps, apps export your hikes and runs in it, and open data portals publish everything from bus stops to flood zones as GeoJSON files.
Why is longitude first in GeoJSON?
Because the standard treats a coordinate as a mathematical (x, y) pair, and longitude is the horizontal x axis. RFC 7946 fixed the order as longitude, latitude for all GeoJSON everywhere, which at least makes the rule universal: any GeoJSON you meet, from any source, follows it.
What is the difference between GeoJSON and JSON?
JSON is the general text structure, labeled values in braces and brackets, used for every kind of data. GeoJSON is JSON with a geographic contract: specific type names (Feature, Point, Polygon), coordinates in longitude-latitude order, and WGS 84 as the only coordinate system. Every GeoJSON file is valid JSON; most JSON is not GeoJSON.
How do I open a GeoJSON file?
Drag it into geojson.io in a browser for an instant map, open it in QGIS for serious work, or paste it into any online GeoJSON viewer. Programmers load it in one line in most languages. If a viewer shows nothing, run the ocean test from this article; the file is probably fine except for swapped pairs.
Can GeoJSON hold more than locations?
Yes: the properties half of each feature holds anything you can write as text, numbers, or lists: names, categories, measurements, timestamps, links. A GeoJSON of weather stations carries temperatures; one of property sales carries prices. The geometry says where, the properties say everything else, and that division is the format's whole design.
Is GeoJSON the same as the data in OpenStreetMap?
Related, not identical. OpenStreetMap keeps its own internal data model of nodes, ways, and relations with tags. GeoJSON is one of the formats OSM data gets exported into for use elsewhere, and many tools translate between them. Think of OSM as a living database and GeoJSON as one of the envelopes its contents travel in.
How big can a GeoJSON file get?
As big as your patience and your users' connections allow, and that is its main weakness: text is verbose, and a file describing every building in a city can run to hundreds of megabytes, which browsers will not forgive. Professionals thin such data before publishing, simplifying outlines and splitting files by area or theme. For the scale of personal and small-team projects, a first file of a few dozen features, size is a non-issue, and GeoJSON's readability is worth far more than the bytes it spends.
Photo credits: Brett Sayles (Pexels); ThisIsEngineering (Pexels). Photos are served from this site; follow the credit to the library page for the original.