From 6fad241314c02cfdb27630f51a6367b567f360dc Mon Sep 17 00:00:00 2001 From: Julian Simioni Date: Mon, 19 Aug 2019 16:39:05 -0400 Subject: [PATCH] feat(docs): Move table of params to sections This layout is much more readable and allows for additional explanation. --- README.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 1ce50cf4..00764860 100644 --- a/README.md +++ b/README.md @@ -54,16 +54,81 @@ Other types may be included in the future. This importer is configured using the [`pelias-config`](https://github.com/pelias/config) module. The following configuration options are supported by this importer. -| key | required | default | description | -| --- | --- | --- | --- | -| `imports.whosonfirst.datapath` | yes | | full path to where Who's on First data is located (note: the included [downloader script](#downloading-the-data) will automatically place the WOF data here, and is the recommended way to obtain WOF data) | -| `imports.whosonfirst.importPostalcodes` | no | false | set to `true` to include postalcodes in the data download and import process | -| `imports.whosonfirst.importVenues` | no | false | set to `true` to include venues in the data download and import process | -| `imports.whosonfirst.importPlace` | no | | set to a WOF id (number or string) indicating the region of interest, only data pertaining to that place shall be downloaded. Use the WOF [spelunker tool](https://spelunker.whosonfirst.org) search for an ID of a place. | -| `imports.whosonfirst.missingFilesAreFatal` | no | false | set to `true` for missing files from [Who's on First bundles](https://dist.whosonfirst.org/bundles/) to stop the import process | -| `imports.whosonfirst.maxDownloads` | no | 4 | the maximum number of files to download simultaneously. Higher values can be faster, but can also cause donwload errors | -| `imports.whosonfirst.dataHost` | no | `https://dist.whosonfirst.org/` | The location to download Who's on First data from. Changing this can be useful to use custom data, pin data to a specific date, etc | -| `imports.whosonfirst.sqlite` | no | false | Set to `true` to use Who's on First SQLite databases instead of GeoJSON bundles. | +### `imports.whosonfirst.datapath` + +* Required: yes +* Default: `` + +Full path to where Who's on First data is located (note: the included [downloader script](#downloading-the-data) will automatically place the WOF data here, and is the recommended way to obtain WOF data) + +### `imports.whosonfirst.importPlace` + +* Required: no +* Default: `` + +Set to a WOF ID or array of IDs to import data only for descendants of those records, rather than the entire planet. + +You can use the [Who's on First Spelunker](https://spelunker.whosonfirst.org) or the `source_id` field from any WOF result of a Pelias query to determine these values. + +Specifying a value for `importPlace` will download the full planet SQLite database (27GB). Support for individual country downloads [may be added in the future](https://github.com/pelias/whosonfirst/issues/459) + +### `imports.whosonfirst.importVenues` + +* Required: no +* Default: `false` + +Set to true to enable importing venue records. There are over 15 million venues so this option will add substantial download and disk usage requirements. + +It is currently [not recommended to import venues](https://github.com/pelias/whosonfirst/issues/94). + + +### `imports.whosonfirst.importPostalcodes` + +* Required: no +* Default: `false` + +Set to true to enable importing postalcode records. There are over 3 million postal code records. + +Setting this option to `true` is well tested and [may become the default in the future](https://github.com/pelias/config/issues/61). + +### `imports.whosonfirst.missingFilesAreFatal` + +* Required: no +* Default: `false` + +Set to `true` for missing files from [Who's on First bundles](https://dist.whosonfirst.org/bundles/) to stop the import process. + +This flag is useful if you consider it vital that all Who's on First data is successfully imported, and can be helpful to guard against incomplete downloads or other types of failure. + +### `imports.whosonfirst.maxDownloads` + +* Required: no +* Default: `4` + +The maximum number of files to download simultaneously. Higher values can be faster, but can also cause donwload errors. + +### `imports.whosonfirst.dataHost` + +* Required: no +* Default: `https://dist.whosonfirst.org/` + +The location to download Who's on First data from. Changing this can be useful to use custom data, pin data to a specific date, etc. + +### `imports.whosonfirst.sqlite` + +* Required: no +* Default: `false` + +Set to `true` to use Who's on First SQLite databases instead of GeoJSON bundles. + +SQLite databases take up less space on disk and can be much more efficient to +download and extract. + +This option may [become the default in the near future](https://github.com/pelias/whosonfirst/issues/460). + +However, both the Who's on First processes to generate +these files and the Pelias code to use them is new and not yet considered +production ready. ## Downloading the Data