How do I upload a location list?

Location lists represent a collection of geospatial coordinates that can be used in orders and analytics.

Pushing Your List to Narrative

You need an active account to send list files to Narrative. If you do not have an account please contact your Narrative partner success representative.

Narrative leverages AWS S3 as it's ingestion point for customer lists. Data is stored in separate buckets for each partner with the typical naming convention being:

narrative-from-<partner_name> 

You can receive your bucket and the appropriate credentials from your partner success representative.

Lists are pushed to a folder within your bucket called:

 lists_incoming

Once pushed to that location Narrative will pick up the file(s) and process the lists. The appropriate file format is discussed below.

Example Push Location: 

narrative-from-<partner_name>/lists_incoming/<filename>.json

Format

Narrative can process lists of locations in the GeoJSON format representing two different geometry types: points and polygons.

Location lists must be supplied as newline-separated GeoJson objects. Each GeoJson object must be one of the following types: point, polygon, feature. (If feature GeoJson objects are supplied, each feature must have a geometry type of point or polygon. Please consult the RFC for details on how to construct valid GeoJson points, polygons or features).

Note that other valid GeoJson geometry types, including MultiPoint, LineString, MultiLineString, MultiPolygon, GeometryCollection, and FeatureCollection, are not supported at this time.

In a given list, each GeoJson object must have the same type. The geometry type of the entire list is derived from the type of the first geometry in the list. All subsequent geometries that have a different type are considered errors and are NOT ingested.

All location points or polygons of a valid format will be read as a list item; however, there are no checks to see whether a point or polygon is a true location. If invalid location points are added, a data buyer will find that location data matching the invalid locations is not available in their order.

Examples

Location Lists

{"type": "Point", "coordinates": [36.0, -118.1]}
{"type": "Point", "coordinates": [37.0, -119.1]}

{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}
{"type":"Polygon","coordinates":[[[200.0,0.0],[221.0,0.0],[201.0,1.0],[200.0,1.0],[200.0,0.0]]]}

{"type":"Feature","geometry":{"type":"Point","coordinates":[102.0,0.5]},"properties":{"prop0":"value0"}}
{"type":"Feature","geometry":{"type":"Point","coordinates":[202.0,1.5]},"properties":{"prop0":"value0"}}

Invalid Location Lists

{"type":"Feature","geometry":{"type":"LineString","coordinates":[[102.0,0.0],[103.0,1.0],[104.0,0.0],[105.0,1.0]]}
{"type":"Feature","geometry":{"type":"LineString","coordinates":[[202.0,0.0],[203.0,1.0],[204.0,0.0],[205.0,1.0]]}

LineString geometries are not supported.

{"type":"Polygon","coordinates":[[[100.0,0.0],[101.0,0.0],[101.0,1.0],[100.0,1.0],[100.0,0.0]]]}
{"type": "Point", "coordinates": [37.0, -119.1]}

While the above list will be processed, it will only contain a single item — the Polygon — as Points are not permitted in a Polygon list.

{"type": "Point", "coordinates": [36.0, -118.1]}{"type": "Point", "coordinates": [37.0, -119.1]}

GeoJson objects must be newline separated.

Filtering with Location Lists

Location list constraints are used by buyers or sellers of data to limit location data bought or sold to specific geographical areas. As with other list constraints, location list constraints come in two flavors:

  1. Inclusion lists - Buyers or sellers can limit the data transacted upon to only those originating from a certain area.
  2. Exclusion lists - Buyers or sellers can limit the data transacted upon to those originated from everywhere except the indicated area.

Additionally, when Narrative has identified that the partner has supplied a list of location points, users will be able to define a point radius in meters when creating a location list constraint.