Ingesting Shapefiles via S3 Buckets

The process of ingesting shapefiles via S3 buckets is relatively straightforward: simply drop a ZIP archive with all the necessary shapefile files into the S3 bucket. However, for some types of shapefiles, some preparation might be necessary, particularly with telling the process how to map shapefile data to vector item fields.

Shapefile mapping file locations#

The shapefile ingestion process requires a file to describe how to map shapefile columns to vector index fields. That file can be located in one of three different places:

  • internal to the ZIP archive
  • at the root of the S3 bucket
  • in a database on the processing system

In the event that mappings for a bucket exist in more than one place, the mapping internal to the zip takes precedence over the mapping in the S3 bucket, which in turn takes precedence over the mapping in the database.

Internal mapping file#

Each ZIP archive for shapefiles can contain a file called "". If the ingestion process finds a file with that name in the ZIP archive, it will use that file to map shapefile columns to vector item fields.

S3 bucket root#

If the ingestion process does not find the mapping file in the ZIP, then it will look at the root of the S3 bucket for the mapping file. The file there should also be named "".

Database entry#

If a mapping file isn't found either in the ZIP or in the S3 bucket, the ingestion process will attempt to look up the bucket name in a database. If it finds an entry with a mapping for the bucket, it will use that mapping. If it doesn't, it will not process the shapefile since there are no more automatic places to look for mappings.

Mapping file format#

A field mapping file defines some information needed by the ingestion process to handle the shapefile, as well as defining some standard fields and default values to use. Note, all columns from a shapefile entry are also automatically included in the 'attributes' map of a vector item.

A field mapping file must include an entry defining the coordinate reference system of the entries in the shapefile. For example:

A few other default values can be defined for all items in the shapefile:


For example:

 vector.itemType=Nepal Earthquake

As well, the index to which the items in the shapefile will be written can be specified by using the vector item index name template format (described here: Vector Services Elasticsearch Index Name Templates). To specify a particular index, include the 'vector.index' property. For example:

The default value for the index name template if the property is not included when ingesting from S3 is:

Finally, shapefile fields can be mapped directly to vector item fields by defining a line with the shapefile column name and an '=' followed by the vector item field. The vector item fields that can be mapped are as follows:

  • item_date
  • name
  • item_type
  • text
  • source

For all of the above values except 'text', the value is taken directly from the column value and converted to the proper type (e.g. an 'item_date' field is converted to a Date). For text, the value of any field mapped to the 'text' type is appended to a single pipe-delimited string. For example, if a shapefile included columns named "fieldOne" and "fieldTwo", and an entry had the corresponding values "valueOne" and "valueTwo", if those fields were both mapped to the 'text' field, the final value would be "valueOne | valueTwo".

A complete mapping file for a shapefile that contains at least columns with the names "tagger_id" and "id" might look as follows:
vector.itemType=Nepal Earthquake