NgwConnector

A lightweight HTTP client optimized for use with NextGIS Web API.

Use this package when an application needs NextGIS Web resources, features, or other HTTP API operations without a map. Ready-to-use ngw-* map packages expose an initialized connector as ngwMap.connector.

npx @nextgis/ngw-types-loader https://your-ngw-server.com
Copy

Make sure CORS is registered in the NextGIS Web settings to be able to send requests.

Installation

In Browser

Include assets

Simply download and include with a script tag, NgwConnector will be registered as a global variable.

<script src="../lib/ngw-connector.global.js"></script>

<script>
  var ngwConnector = new NgwConnector({
    baseUrl: 'https://demo.nextgis.com',
  });
</script>
Copy

CDN

unpkg

<script src="https://unpkg.com/@nextgis/ngw-connector"></script>
Copy

jsdelivr

<script src="https://cdn.jsdelivr.net/npm/@nextgis/ngw-connector"></script>
Copy

We recommend linking to a specific version number /ngw-connector@[version]

In Node.js

npm install @nextgis/ngw-connector
Copy

TypeScript Support

NgwConnector.route() uses declarations generated by NextGIS Web itself. Install the loader as a development dependency:

npm install --save-dev @nextgis/ngw-types-loader
Copy

Then generate types from the NextGIS Web deployment your application connects to:

npx @nextgis/ngw-types-loader https://your-ngw-server.com
Copy

If the URL is omitted, the loader uses https://demo.nextgis.com:

npx @nextgis/ngw-types-loader
Copy

The declarations are installed as resolvable packages under node_modules/@nextgisweb; no tsconfig.json changes are required. Run the loader again after changing the NextGIS Web version, components, or extensions.

For more details, refer to the NGW Types Loader.

Usage

import NgwConnector from '@nextgis/ngw-connector';

const ngwConnector = new NgwConnector({
  baseUrl: 'https://demo.nextgis.com',
  // auth: {login, password}
});

ngwConnector
  .route('resource.item', { id: 485 })
  .get()
  .then((data) => {
    console.log(data);
  });

ngwConnector.route('resource.collection').patch({ json: RESOURCE });
ngwConnector.route('feature_layer.feature.collection', { id }).patch({
  json: ITEMS,
  query: {
    srs: 4326,
    geom_format: 'geojson',
  },
});
ngwConnector
  .route('feature_layer.feature.item', { id, fid })
  .put({ json: ITEM });
ngwConnector.route('feature_layer.feature.item', { id, fid }).delete();

// Shortcuts methods to find resources
ngwConnector.getResource(2011); // by id
ngwConnector.getResource('keyname'); // by keyname

ngwConnector.getResources({ cls: 'vector_layer', parent__id: 0 }); // find resources by partial resource params
ngwConnector.getResource({ display_name: 'My layer', parent__id: 0 }); // get first
Copy

Typed routes and compatibility methods

Prefer route() for API endpoints represented by the declarations generated by your NextGIS Web deployment. Route names, path parameters, query parameters, and response bodies are derived from @nextgisweb modules.

Methods such as getResource() and getResources() use the compatibility types shipped with ngw-connector. They remain useful for established code and for operations without a generated route declaration. These two type sources are intentionally separate because available server routes depend on installed NextGIS Web components and extensions.

Check out the API Documentation

NGW API

NextGIS Web API Doc

ngwConnector.get(request_name, request_options, arguments);
Copy

request_options

API request names

See also the package architecture guide.

Commercial support

Need to fix a bug or add a feature to @nextgis/ngw-connector? We provide custom development and support for this software. Contact us to discuss options!