Vector Services Write Vectors Reference Overview

Overview of the Generating Vectors API

These endpoints work in any application.

Write Vectors API Parameters#

ParameterData TypeParameter TypeDescriptionRequired?
idStringQueryThe ID of the item.Optional on creation (will be generated automatically if not specified), required for all other write operations
indexStringQueryThe index to which items will be written/are stored. The index is generated during the POST call. Indices are automatically prepended with vector-. Note: All indices generated through the API begin with vector-user-provided. Example: vector-user-provided-testOptional on creation, required after
itemArrayStringQueryJSON array of items to write. Reference example from itemJson.Required for multiple vector item ingest
itemJsonStringQueryGeoJSON of item to write. See itemJson ParametersRequired for single vector item ingest

The index is generated one of two ways, depending on the API call used:

  • Via user input when using the multi-vector write API
  • Automatically when no index is specified; in this case, the index will be vector-user-provided

See Vector Services Elasticsearch Index Name Templates for information on user defined index name generation.

itemJson Parameters##

ParameterData TypeParameter TypeDescriptionRequired?
geometryObjectBodyIncludes the geometry type and the geojson coordinates of the vector. Note: When sending vector write requests via the API, we require EPSG:4326 for our GeoJSON. For example, "geometry": { "type": "Point", "coordinates": [1.0,1.0] }Required
propertiesObjectBodyThe defined GeoJson fields for vector information. See Properties Sub-Part ParametersRequired
typeStringBodyType of json object. Typically, this type is Feature. For Example, "type": "Feature"Required

Properties Sub-Part Parameters###

ParameterData TypeParameter TypeDescriptionRequired?
attributesObjectBodyAny additional information associated with the vector. Note: attributes may include objects.Optional
formatStringBodyThe format the original data was in. For example, GeoJSON, shapefile, etcOptional
geom_typeStringBodyBased on the geometry type, automatically generated based on the item geometry.Optional; generated on vector ingest
idStringBodyThe uuid associated with the vector in VectorServices. VectorServices will provide the id as the vector is ingested.Generated on vector ingest
ingest_attributesObjectBodyAttributes specific to the ingestion process. VectorServices automatically generates this information on ingest.Optional; generated on vector ingest
ingest_dateStringBodyThe datetime associated with the vector entering VectorServices, in ISO-8601 format YYYY-MM-DDThh:mm:ss.fffZ (ex: 2016-31-01T14:12:28.011Z).Optional; generated on vector ingest
ingest_sourceStringBodyWhere the data got into the vector services system. For example, the Write API. Note: This can be used to represent the source of the vectors, if desired.Required
item_dateStringBodyThe datetime associated with the generation of the vector itself, in ISO-8601 format YYYY-MM-DDThh:mm:ss.fffZ (ex: 2016-31-01T14:12:28.011Z). Note: If item_date is not specified, the date and time of ingest will be inserted into item_date.Optional
item_typeStringBodyThe type of vector, in human-readable format. This is often not a unique name. For instance, "Road"Required
nameStringBodyThe specific name of the vector item. For instance, "Alameda Avenue"Optional
sourceStringBodyThe original source of the data. For instance, "ACLED" or "Twitter" or "OSM"Optional
textStringBodyFree-form text associated with the vector; text in this field is searchable when querying in VectorServices. For instance, if the vector is associated with a flood, an event description could be included in the text.Required

All itemJson parameters put together would look something like:

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [1.0,1.0]
    },
    "properties": {
        "text" : "Fantasy land elementary school",
        "name" : "Mothra",
        "item_type" : "School",
        "ingest_source" : "API test source",
        "source" : my_brain,
        "format" : shapefile,
        "item_date": "2018-09-04T12:41:15.001Z",
        "attributes" : {
            "institute.founded" : "2015-07-17",
            "mascot" : "moth",
            "attr_obj" : {
                "objects" : "object 1",
                "diff_objects" : "object 2"
            }
        }
    }
}

Note: id, ingest_attributes, geom_type, and ingest_date were all excluded from the example due to VectorServices generating this information on ingest.

Note: VectorServices does not handle field names that include dots. Geojson that includes fields with dots (for example, location.name) will be rejected. Convert fields with dots before submission.

Associated API Calls for Write Vector Services#

Adding Multiple Vector Items
Adding Single Vector Item
Batch Deleting Vectors via item ID
Deleting Single Vector Item
Retrieving Single Vector Item
Updating Single Vector Item