diff --git a/docs/integrations/postgis.rst b/docs/integrations/postgis.rst index 7696f45bc5..7a093fe6b8 100644 --- a/docs/integrations/postgis.rst +++ b/docs/integrations/postgis.rst @@ -3,7 +3,7 @@ PostGIS ======= -You can use the string representation for `PostGIS `_ data types such as ``geometry`` or ``geography`` (you need to `install PostGIS `_ first). +To work with `PostGIS `_ data types such as ``geometry`` or ``geography``, you'll need to `install PostGIS `_ first. .. code-block:: postgres @@ -16,20 +16,16 @@ You can use the string representation for `PostGIS `_ data area geometry ); -To add areas in polygon format, you can use string representation: + insert into coverage (id, name, area) values + (1, 'small', ST_GeomFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))',4326)), + (2, 'big', ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))', 4326); -.. code-block:: bash +.. _application/geo+json: - curl "http://localhost:3000/coverage" \ - -X POST -H "Content-Type: application/json" \ - -d @- << EOF - [ - { "id": 1, "name": "small", "area": "SRID=4326;POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" }, - { "id": 2, "name": "big", "area": "SRID=4326;POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))" } - ] - EOF +``application/geo+json`` +------------------------ -Now, when you request the information, PostgREST will automatically cast the ``area`` column into a ``Polygon`` geometry type. Although this is useful, you may need the whole output to be in `GeoJSON `_ format out of the box, which can be done by including the ``Accept: application/geo+json`` in the request. This will work for PostGIS versions 3.0.0 and up and will return the output as a `FeatureCollection Object `_: +PostgREST supports the `standard `_ ``application/geo+json`` media type which can be used to get the output in `GeoJSON `_ format. This will work for PostGIS versions 3.0.0 and up and will return the output as a `FeatureCollection Object `_: .. code-block:: bash @@ -70,6 +66,9 @@ Now, when you request the information, PostgREST will automatically cast the ``a ] } +Using generated columns +----------------------- + If you need to add an extra property, like the area in square units by using ``st_area(area)``, you could add a generated column to the table and it will appear in the ``properties`` key of each ``Feature``. .. code-block:: postgres @@ -135,3 +134,21 @@ Now this query will return the same results: } ] } + +Using string representation +--------------------------- + +To insert areas in polygon format, you can use string representation: + +.. code-block:: bash + + curl "http://localhost:3000/coverage" \ + -X POST -H "Content-Type: application/json" \ + -d @- << EOF + [ + { "id": 3, "name": "strip", "area": "SRID=4326;POLYGON((0 0, 50 0, 50 2, 0 2, 0 0))" }, + { "id": 4, "name": "diamond", "area": "SRID=4326;POLYGON((5 0, 10 5, 5 10, 0 5, 5 0))" } + ] + EOF + +PostgREST will automatically cast the ``area`` column into a ``Polygon`` geometry type. diff --git a/docs/references/api/resource_representation.rst b/docs/references/api/resource_representation.rst index c4e841c43f..a02dcd3e48 100644 --- a/docs/references/api/resource_representation.rst +++ b/docs/references/api/resource_representation.rst @@ -51,7 +51,7 @@ Builtin handlers are offered for common standard media types. * ``text/csv`` and ``application/json``, for all API endpoints. See :ref:`tables_views` and :ref:`functions`. * ``application/openapi+json``, for the root endpoint. See :ref:`open-api`. -* ``application/geo+json``, see :ref:`ww_postgis`. +* ``application/geo+json``, see :ref:`application/geo+json`. * ``*/*``, resolves to ``application/json`` for API endpoints and to ``application/openapi+json`` for the root endpoint. The following vendor media types handlers are also supported.