GeoJSON es el formato basado en JSON que cada mapa web moderno puede leer. Si alguna vez has dibujado un polígono sobre un mapa de Leaflet, estilizado una capa vectorial en MapLibre o guardado un área de servicio en PostGIS, has estado trabajando con GeoJSON, aunque la extensión del archivo dijera otra cosa.
Esta guía explica qué es realmente GeoJSON, qué significan sus tipos de geometría, dónde aparece en sistemas reales y los errores que muerden a los equipos cuando los archivos GeoJSON salen del portátil de un developer y golpean producción.
Qué es realmente GeoJSON
GeoJSON es un formato abierto para codificar estructuras de datos geográficos, estandarizado por el IETF como RFC 7946 en 2016. Es un subconjunto estricto de JSON: cada documento GeoJSON es JSON válido, pero la spec añade reglas sobre qué keys están permitidas, cómo se estructura la geometría y cómo se ordenan las coordenadas.
El formato es deliberadamente pequeño. Solo hay nueve tipos de objeto de nivel superior en toda la spec, y un developer competente puede tener todos en la cabeza. Esa pequeñez es por la que GeoJSON se ha convertido en la lingua franca del web mapping: es fácil de leer, fácil de escribir y fácil de validar.
Las coordenadas siempre se escriben como [longitud, latitud] (con altitud opcional como tercer valor) y el sistema de referencia de coordenadas está fijado a WGS84, el mismo datum que usa el GPS de tu móvil. No hay negociación, ni metadatos de proyección, ni debate sobre el orden de los ejes. Un datum, un orden, en todas partes.
Tipos de geometría
GeoJSON define siete tipos de geometría. Los tres primeros son las primitivas:
- Point: una sola coordenada, usada para pins, direcciones y sensores individuales
- LineString: una lista ordenada de dos o más coordenadas, usada para rutas, carreteras y ríos
- Polygon: un anillo cerrado de coordenadas (primer y último punto idénticos), usado para edificios, parcelas y límites administrativos
Los tres siguientes son simplemente colecciones de esas primitivas:
- MultiPoint: muchos puntos en una sola geometría, útil para representar una cadena de tiendas como una sola feature
- MultiLineString: muchos line strings, usado para rutas fragmentadas o sistemas de ríos
- MultiPolygon: muchos polígonos, la opción correcta para cualquier país con islas (es decir, casi todos)
El séptimo, GeometryCollection, puede contener una mezcla de cualquiera de los anteriores. La spec lo desaconseja porque la mayoría de consumidores lo manejan mal y casi nunca lo necesitas. Si echas mano de GeometryCollection, suele ser señal de que el modelo quiere ser una FeatureCollection.
Feature y FeatureCollection
Una geometría sola rara vez es útil. Necesitas saber qué representa. Para eso está Feature: una Feature envuelve una geometría con un objeto properties que guarda metadatos arbitrarios.
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [4.8952, 52.3702]
},
"properties": {
"name": "Amsterdam Centraal",
"type": "station",
"platforms": 15
}
}
Una FeatureCollection es una lista de Features. Casi cualquier archivo GeoJSON real que te encuentres por ahí es una FeatureCollection, porque los datasets reales tienen muchas cosas dentro.
La decisión clave de diseño es que properties está abierto. La spec no dice nada sobre qué keys puede contener ni de qué tipos deberían ser esos valores. Eso es una feature, no un bug: significa que GeoJSON sirve para mobiliario urbano, distritos electorales, zonas de delivery y trazas AIS de barcos sin tener que extender el formato. También significa que los consumidores tienen que tener cuidado: si dependes de que properties.population exista, valídalo tú, porque RFC 7946 no lo va a hacer.
Dónde aparece GeoJSON
Una vez te fijas, GeoJSON está en todas partes en el stack geoespacial:
- Librerías de mapas: MapLibre GL, Mapbox GL, Leaflet y OpenLayers consumen todos GeoJSON de forma nativa como fuente de datos para capas
- Pipelines de vector tiles: herramientas como Tippecanoe toman GeoJSON de entrada y producen sets de MVT (Mapbox Vector Tile)
- Specs de estilo de mapa: la Mapbox Style Specification, usada por MapLibre, referencia GeoJSON como un tipo de fuente de primera clase
- Bases de datos espaciales: PostGIS, BigQuery GIS y Snowflake importan y exportan todos GeoJSON mediante funciones dedicadas
- Outputs de API: la mayoría de geocoding, isochrone y routing APIs modernas devuelven Features GeoJSON para los resultados, así la respuesta puede soltarse directamente sobre un mapa
- Polylines de ruta: las respuestas de navegación incluyen comúnmente una geometría LineString para la ruta, lista para renderizar
- Compartición de datos: portales de open data, exports de OpenStreetMap y publicaciones de límites gubernamentales usan GeoJSON por defecto cuando van dirigidos a usuarios web
Si una herramienta puede hablar cualquier formato geoespacial, casi seguro habla GeoJSON.
Errores en producción
GeoJSON es indulgente el primer día e implacable el día noventa. Las trampas que pillan a los equipos:
Longitud primero. RFC 7946 fija el orden como [lon, lat]. Los humanos, las direcciones y la mayoría de la documentación escriben lat, lon. Intercambiarlos es el bug más común de GeoJSON, y tu punto acaba en el océano equivocado.
Orden de winding del polígono. RFC 7946 especifica que los anillos exteriores deben ser counter-clockwise y los anillos interiores (huecos) clockwise. Muchos archivos GeoJSON antiguos ignoran esto. Algunos renderizadores no se enteran, otros (especialmente Mapbox GL con polígonos que cruzan el antimeridiano) renderizan el polígono como el inverso de lo que querías: una islita pequeña se convierte en un agujero en el océano que cubre el resto del mundo.
Manejo del antimeridiano. Una geometría que cruza el meridiano 180/-180 hay que partirla según la spec. Los polígonos ingenuos dibujados a través del Pacífico se renderizan como una franja fina envuelta dando la vuelta larga al planeta.
Sin soporte nativo de CRS más allá de WGS84. RFC 7946 retiró deliberadamente el antiguo miembro crs. Si tus datos están en una cuadrícula nacional (British National Grid, RD New, EPSG:3857), tienes que reproyectar a WGS84 antes de serializar. Las herramientas que emiten GeoJSON no-WGS84 son técnicamente no-conformes.
Tamaño del archivo. Una FeatureCollection con millones de polígonos detallados puede inflarse a gigabytes. Para entrega al navegador, cambia a vector tiles, simplifica geometría con Douglas-Peucker o haz streaming con GeoJSON delimitado por saltos de línea (.ndjson).
Validación. Usa un linter como GeoJSONLint o la librería geojson-validation en CI. Pillar un orden de winding inválido o coordenadas intercambiadas en build es más barato que pillarlo desde un ticket de cliente.
GeoJSON en MapAtlas
GeoJSON es el formato de intercambio de datos por defecto en toda la plataforma de MapAtlas. El producto Dynamic Maps acepta fuentes GeoJSON directamente para overlays personalizados, estilizado y capas interactivas, sin preprocesamiento.
La API de Geocoding devuelve direcciones emparejadas como Features GeoJSON, así un resultado de forward geocode puede soltarse directamente sobre un mapa o guardarse en PostGIS sin remapear campos. La API de isócronas devuelve áreas de tiempo de viaje como polígonos GeoJSON, lo que significa que una query de "lugares alcanzables en 15 minutos" está a un fetch y un addSource de estar en pantalla.
GeoJSON no es glamuroso. Es un subconjunto pequeño y opinionado de JSON con un orden fijo de coordenadas y un puñado de tipos de geometría. Pero es el formato que permite a cada capa de un stack moderno de localización, desde la base de datos espacial hasta el canvas del mapa, ponerse de acuerdo en qué es un lugar. Acierta con el orden de la longitud, valida el winding y el resto del stack tiende a cuidar de sí mismo.
Preguntas frecuentes
¿Qué es GeoJSON?
GeoJSON es un formato abierto basado en JSON para codificar datos geográficos, estandarizado como RFC 7946 por el IETF. Define un pequeño conjunto de tipos de geometría (Point, LineString, Polygon, y sus variantes multi) más los objetos Feature y FeatureCollection que envuelven una geometría con propiedades arbitrarias. Las coordenadas siempre se escriben como longitud, latitud sobre el datum WGS84, que es lo que espera toda librería moderna de mapas web.
¿Cuál es la diferencia entre GeoJSON y JSON?
GeoJSON es un subconjunto estricto de JSON con reglas extra. Cada documento GeoJSON es JSON válido, pero no todo documento JSON es GeoJSON válido. La spec fija los tipos de objeto de nivel superior, la estructura de los objetos de geometría, el orden de las coordenadas (longitud primero) y el sistema de referencia de coordenadas (WGS84). Cualquier cosa fuera de esas reglas es solo JSON que casualmente contiene datos geográficos.
¿Cuándo debería usar GeoJSON en vez de un shapefile o KML?
Usa GeoJSON siempre que los datos tengan que fluir por un stack web: APIs, navegadores, bases de datos como PostGIS, o cualquiera entre MapLibre, Leaflet, Mapbox GL u OpenLayers. Los shapefiles siguen siendo comunes en GIS de escritorio pero llegan en cuatro o más archivos y usan un formato binario de los noventa. KML está bien para Google Earth pero es verboso y basado en XML. GeoJSON gana para cualquier cosa que toque APIs JSON.
¿Por qué las coordenadas de GeoJSON van con la longitud primero?
RFC 7946 fija el orden como longitud, latitud, altitud opcional. Esto coincide con la convención x, y, z usada en la mayoría de sistemas de gráficos y GIS. Es lo opuesto a cómo escriben los humanos las coordenadas (latitud primero, como en 51.5, -0.1) y es el bug más común al hacer GeoJSON a mano: intercambia los dos valores y tu punto cae en el hemisferio equivocado. Siempre longitud primero en GeoJSON.
