.. _vector.esrijson:

ESRIJSON / FeatureService driver
================================

.. shortname:: ESRIJSON

.. built_in_by_default::

This driver can read the JSON output of Feature Service requests
following the `GeoServices REST
Specification <http://www.esri.com/industries/landing-pages/geoservices/geoservices.html>`__,
like implemented by `ArcGIS Server REST
API <http://help.arcgis.com/en/arcgisserver/10.0/apis/rest/index.html>`__.
The driver can scroll through such result sets
that are spread over multiple pages (for ArcGIS servers >= 10.3). This
is automatically enabled if URL does not contain an explicit
*resultOffset* parameter. If it contains this parameter and scrolling is
still desired, the :oo:`FEATURE_SERVER_PAGING` open option must be set to YES.
The page size can be explicitly set with the *resultRecordCount*
parameter (but is subject to a server limit). If it is not set, OGR will
set it to the maximum value allowed by the server.

Note: for paged requests to work properly, it is generally necessary to
add a sort clause on a field, typically the OBJECTID with a
"&orderByFields=OBJECTID+ASC" parameter in the URL, so that the server
returns the results in a reliable way.

Driver capabilities
-------------------

.. supports_georeferencing::

.. supports_virtualio::

Datasource
----------

The driver accepts three types of sources of data:

-  Uniform Resource Locator (`URL <http://en.wikipedia.org/wiki/URL>`__)
   - a Web address to perform
   `HTTP <http://en.wikipedia.org/wiki/HTTP>`__ request.
-  Plain text file with ESRIJSON data - identified from the file
   extension .json
-  Text passed directly and encoded in ESRI JSON

The URL/filename/text might be prefixed with
ESRIJSON: to avoid any ambiguity with other drivers. Alternatively, starting
with GDAL 3.10, specifying the ``-if ESRIJSON`` option to command line utilities
accepting it, or ``ESRIJSON`` as the only value of the ``papszAllowedDrivers`` of
:cpp:func:`GDALOpenEx`, also forces the driver to recognize the passed
URL/filename/text.


Open options
------------

|about-open-options|
The following open options are supported:

-  .. oo:: FEATURE_SERVER_PAGING
      :choices: YES, NO

      Whether to automatically scroll
      through results with a ArcGIS Feature Service endpoint. Has only effect
      for ArcGIS servers >= 10.3 and layers with supportsPagination=true capability.

-  .. oo:: HTTP_METHOD
      :choices: AUTO, GET, POST
      :default: AUTO
      :since: 3.13

      Which HTTP request method to use to send requests to the server. In AUTO
      mode (the default), GET will be used, unless the URL exceeds 256 characters.
      When it does, the query parameters (the part of the URL after '?') will
      be sent in the body of a POST request.

Examples
--------

.. example::
   :title: Read the result of a FeatureService request against a GeoServices REST server

   Note that this server does not support paging.

   .. code-block:: bash

      ogrinfo -ro -al "https://sampleserver6.arcgisonline.com/arcgis/rest/services/PoolPermits/FeatureServer/0/query?resultRecordCount=10&f=pjson"

See Also
--------

-  :ref:`GeoJSON driver <vector.geojson>`
-  `GeoServices REST Specification <https://geoservices.github.io/>`__
