Custom Data Provider API Reference

This topic discusses the custom data provider specification.

Registration Object

Every custom data provider has a file named index.js that exports a registration object containing provider information. The object describes how to load and use the provider. The following is the code that is automatically included in the index.js file by the Custom Data Feeds (CDF) command line tool.

1
2
3
4
5
6
7
8
9
10
11
const packageInfo = require('../package.json');
const csconfigInfo = require('../cdconfig.json');
const provider = {
  type: csconfigInfo.type,
  name: csconfigInfo.name,
  version: packageInfo.version,
  hosts: csconfigInfo.properties.hosts,
  disableIdParam: csconfigInfo.properties.disableIdParam,
  Model: require('./model')
};
module.exports = provider;

The table below describes each field in detail:

The auto-generated code pulls the provider version from the package.json file and other fields from the cdconfig.json file. To modify these fields, change the corresponding values in the cdconfig.json file instead of the index.js file.

Model Class

Every custom data provider implements a Model class, which is usually in the model.js file. The Model class includes a getData function that will contain code for fetching and tranforming remote data into GeoJSON. The following table describes the arguments that the getData function accepts.

Request Object

The following code snippet illustrates how to retrieve the host and id URL parameters from the request object:

1
2
const host = req.params.host;
const id = req.params.id;

The host parameter will only appear if the value of the host field in the cdconfig.json file is set to true. Similarly, the id parameter will only appear if the value of the disableIdParam field in the cdconfig.json file is set to false. You can use these parameters to build the URL to the remote data source.

Callback Function

Pass the constructed GeoJSON to the callback function inside the getData function as follows.

callback(null,geojson);

If an error occurs, invoke the callback function with the error as follows:

1
callback(err);

GeoJSON Metadata

Custom Data Feeds requires that the GeoJSON be decorated with a property called metadata. It should have an object as its value. This object contains information important for translating the GeoJSON to its feature service equivalent. The table below describes some of the key metadata properties:

If your data does not contain a field that can be used as the OBJECTID, you can leave idField undefined. In such cases Custom Data Feeds will create an OBJECTID for each feature by default. However, this is less than ideal as it impacts performance and in very rare cases may lead to OBJECTID collisions. The best practice is to have a field on the raw data that meets the requirements of idField.

Routes and Controllers

Routes

To use provider-specific routes, ensure that the routes field in the index.js file points to a file that exports an array of route definition objects. The following table describes the fields that each route definition object must contain.

Controllers

Set the handler field of each route definition object to the function name that handles requests for that route. You can define these functions in a Controller class. The Controller field in the index.js file must reference the Controller class. Below is an example of how to implement a Controller class.

1
2
3
4
5
6
function Controller (model) {
  this.model = model;
}
Controller.prototype.test = function (req, res) {
  res.status(200).json({version: '1.0.0'});
};