package ground.v1beta1

Get desktop application:
View/edit binary Protocol Buffers messages

Audit info about *who* performed a particular action and *when*.

Used in: LocationOfInterest, Submission

• string user_id = 1

  Required. The id of the user performing the action.

• optional google.protobuf.Timestamp client_timestamp = 2

  Required. Time and date reported by the client.

• optional google.protobuf.Timestamp server_timestamp = 3

  Required. Time and date reported by the server.

• string display_name = 4

  The user-facing name of the user.

• string photo_url = 5

  URL of the user's profile picture.

• string email_address = 6

  The user's email address.

A pair of coordinates in the WGS 84 Web Mercator system.

Used in: LinearRing, Point, TaskData.CaptureLocationResult

• double latitude = 1

  Required. WGS 84 latitude.

• double longitude = 2

  Required. WGS 84 longitude.

An arbitrary geometry, represented using WGS 84 Web Mercator coordinate system. Designed for compatibility with Google Maps Platform and GeoJSON format defined at geojson.org.

Used in: LocationOfInterest, TaskData.DrawGeometryResult

• oneof geometry_type

  Required. A geometry may be one of the following types:

  • Point point = 1

    A point geometry.

  • Polygon polygon = 2

    A polygon geometry.

  • MultiPolygon multi_polygon = 3

    A multi-polygon geometry.

A single job, defined by one or more tasks, and associated with zero or more locations of interest (aka data collection sites) by ID.

• string id = 1

  Required. The system-defined unique identifier of this entity.

• int32 index = 2

  Required. Index of the job when shown in lists.

• string name = 3

  User-facing name of the job.

• optional Style style = 4

  The style used when rendering geometries and other UI elements associated with this job.

• repeated Task tasks = 5

  One or more data collection tasks to be carried out by the user in order to collect and submit data.

A closed line-string with four or more vertices.

Used in: Polygon

• repeated Coordinates coordinates = 1

  Required. The coordinates of the ring's vertices. The first and last positions must contain identical values.

A location of interest (LOI, presented to the user as "[data collection] sites"). All data submitted by data collectors is associated with an LOI.

• string id = 1

  Required. The system-defined unique identifier of this entity.

• string job_id = 2

  Required. The system-defined unique identifier of the job to which this LOI belongs.

• optional Geometry geometry = 3

  Required. The geometry associated with this LOI.

• int32 submission_count = 4

  Required. The number of submissions associated with this LOI.

• string owner_id = 5

  Required. The user ID of the LOI's owner.

• optional AuditInfo created = 6

  Required. Info about who created this LOI and when.

• optional AuditInfo last_modified = 7

  Info about who last modified this LOI and when. If unset, it is assumed the LOI was never modified after it was created.

• string custom_tag = 8

  A user-defined identifier for this LOI, generally imported from the `id` field in GeoJSON Features.

• LocationOfInterest.Source source = 9

  Required. Indicates who created this LOI and when.

• map<string, LocationOfInterest.Property> properties = 10

  Arbitrary key-value pairs associated with this LOI.

A single value associated with an LOI.

Used in: LocationOfInterest

• oneof property_type

  • string string_value = 1

    A string value.

  • double numeric_value = 2

    A numeric value.

Valid values for location of interest `source`.

Used in: LocationOfInterest

• SOURCE_UNSPECIFIED = 0

  Indicates the value was not set.

• IMPORTED = 1

  Indicates the LOI was imported by survey as part of a statistical sampling design or other structured source.

• FIELD_DATA = 2

  Indicates the LOI was added at data collection time.

A multi-polygon geometry.

Used in: Geometry

• repeated Polygon polygons = 1

  Required. The individual polygons comprising the multi-polygon.

A single point on the map.

Used in: Geometry

• optional Coordinates coordinates = 1

  Required. The point's coordinates.

A polygon geometry.

Used in: Geometry, MultiPolygon

• optional LinearRing shell = 1

  Required. The outer shell of the polygon.

• repeated LinearRing holes = 2

  Holes in the polygon, if any.

Defines a user's role in a survey.

Used in: Survey

• ROLE_UNSPECIFIED = 0

  Default value when role is missing.

• VIEWER = 1

  User may access survey in read-only model.

• DATA_COLLECTOR = 2

  User may also submit data, but not modify jobs or other survey metadata.

• SURVEY_ORGANIZER = 3

  User may also manage the survey, update locations of interest, etc.

A style used when rendering geometries and other UI elements associated with this job.

Used in: Job

• string color = 1

Data submitted by data collectors for relevant tasks in a job.

• string id = 1

  Required. The system-defined unique identifier of this entity.

• string loi_id = 2

  Required. The ID of the location of interest to which this submission refers.

• int32 index = 3

  The sequential index in which this task was completed.

• string job_id = 4

  Required. The ID of the job to which this submission refers. This can also be obtained from the location of interest, but is duplicated here to facilitate filtering.

• string owner_id = 5

  Required. The user ID of the submission's owner.

• optional AuditInfo created = 6

  Required. Info about who created this submission and when.

• optional AuditInfo last_modified = 7

  Info about who last modified this submission and when. If unset, the submission was never modified after it was created.

• repeated TaskData task_data = 8

  The data collector's responses to tasks in this job.

Describes a single data collection survey. Top level entity in the app.

• string id = 1

  Required. The system-defined unique identifier of this entity.

• string name = 2

  User-facing name of the survey.

• string description = 3

  User-facing description of the survey.

• map<string, Role> acl = 4

  Defines who has access to do what with this survey.

• string owner_id = 5

  Required. User id of the survey owner.

• optional Survey.DataSharingTerms data_sharing_terms = 6

  Defines the terms data collectors must agree to before collecting data.

• Survey.State state = 7

  Defines the survey's current state.

• Survey.GeneralAccess general_access = 8

  Defines who can access the survey beyond users in the ACLs.

• Survey.DataVisibility data_visibility = 9

  Defines who can see data submitted in this survey.

Defines the terms data collectors must agree to before collecting data.

Used in: Survey

• DataSharingTerms.Type type = 1

  Required. Type of data sharing terms the data collectors must agree to before collecting data.

• string custom_text = 2

  If type is CUSTOM, this field contains the custom data sharing terms text specified by the survey organizer.

Defines the type of data sharing terms the user will see.

Used in: DataSharingTerms

• TYPE_UNSPECIFIED = 0

  Default value when the type is missing.

• PRIVATE = 1

  Data will only be shared with survey organizers.

• PUBLIC_CC0 = 2

  Data can be made public with no constraints. Data collectors waive all rights to collected data, making it available under the CC0 "No Rights Reserved" license.

• CUSTOM = 3

  Terms are defined by survey organizers.

Possible values for the visibility of data in this survey.

Used in: Survey

• DATA_VISIBILITY_UNSPECIFIED = 0

  Default value when visibility unset. Same as CONTRIBUTOR_AND_ORGANIZERS.

• CONTRIBUTOR_AND_ORGANIZERS = 1

  LOIs and submissions can only be viewed by their contributor and survey organizers.

• ALL_SURVEY_PARTICIPANTS = 2

  LOIs and submissions can be viewed by all users with access to this survey.

Possible values for who can access the survey beyond users in the ACLs.

Used in: Survey

• GENERAL_ACCESS_UNSPECIFIED = 0

  Default value when general_access is missing.

• RESTRICTED = 1

  Only users with the DATA_COLLECTOR role in the survey ACLs can contribute.

• UNLISTED = 2

  Anyone with a link or QR Code can contribute.

• PUBLIC = 3

  Anyone can contribute.

Possible values for the survey's current state.

Used in: Survey

• STATE_UNSPECIFIED = 0

  Default value when status is missing.

• DRAFT = 1

  Indicates the survey organizer has not yet completed the survey creation flow.

• READY = 2

  Survey is ready to be used/edited.

A data collection task to be carried out by the user/ to collect and submit data.

Used in: Job

• string id = 1

  Required. The system-defined unique identifier of this entity.

• int32 index = 2

  Index of the task when shown in lists.

• string prompt = 3

  Question or instructions shown to the user describing the task to be completed.

• bool required = 4

  When true, the user may not skip this task.

• Task.DataCollectionLevel level = 5

  Defines to which entity data collected in this task is associated with. Defaults to LOI_DATA.

• repeated Task.Condition conditions = 6

  Conditions which control whether this task is shown during data collection. All conditions must be evaluate to `true` for the task to be triggered.

• oneof task_type

  A task may be exactly one of the following:

  • Task.TextQuestion text_question = 7

    A question whose response is entered manually as text.

  • Task.NumberQuestion number_question = 8

    A question whose response is entered manually as a number.

  • Task.DateTimeQuestion date_time_question = 9

    A question whose response is entered manually as a date and/or time.

  • Task.MultipleChoiceQuestion multiple_choice_question = 10

    A question whose response is manually selected from a list of options.

  • Task.DrawGeometry draw_geometry = 11

    A task in which the user must manually draw a geometry (point, polygon, etc.) on the map.

  • Task.CaptureLocation capture_location = 12

    A task in which the user must capture their current device location.

  • Task.TakePhoto take_photo = 13

    A task in which the user must take a photo.

  • Task.InstructionsTask instructions = 14

    A set of instructions to be shown to the data collector during the data collection process.

A task in which the user must capture their current device location.

Used in: Task

• float min_accuracy_meters = 1

  Required. The minimum accuracy, in meters, required when capturing the current location. Set to 999.0 to represent "no limit".

Defines a single condition used to determine whether a task should be shown.

Used in: Task

• oneof condition_type

  A condition is defined by one of the following constraints:

  • MultipleChoiceSelection multiple_choice = 1

    A condition which passes if any of the specified values are selected.

Defines possible values of the `level` field.

Used in: Task

• DATA_COLLECTION_LEVEL_UNSPECIFIED = 0

  Default value when level is not specified.

• LOI_METADATA = 1

  Data collected at this level is used to define a location of interest (LOI). Specifically, geometry tasks of this type may be used to allow data collectors to define the LOI's geometry. Future implementations may use this to allow other LOI properties to be added or modified.

• LOI_DATA = 2

  Data collected at this level is associated with, but does not define, a location of interest (LOI). Specifically, geometry tasks of this type define one or more annotations of the associated LOI. rather than the geometry of the LOI itself.

A question whose response is entered manually as a data and/or time.

Used in: Task

• DateTimeQuestion.Type type = 1

  Required. The type of data/time question.

Allowed values for the `type` field.

Used in: DateTimeQuestion

• TYPE_UNSPECIFIED = 0

• DATE_ONLY = 1

• TIME_ONLY = 2

• BOTH_DATE_AND_TIME = 3

A task in which the user must manually draw a geometry (point, polygon, etc.) on the map.

Used in: Task

• repeated DrawGeometry.Method allowed_methods = 1

  Required. One or more methods which the user may use to complete the geometry task. If multiple methods are specified, data collectors are prompted which method should be used.

Possible values for the `allowed_methods` field.

Used in: DrawGeometry

• METHOD_UNSPECIFIED = 0

• DROP_PIN = 1

• DRAW_AREA = 2

A set of instructions to be shown to the data collector during the data collection process.

Used in: Task

• string text = 1

  Required. Markdown text to be shown to the user.

A question whose response is manually selected from a list of options.

Used in: Task

• MultipleChoiceQuestion.Type type = 1

  Required. The type of multiple choice question.

• repeated MultipleChoiceQuestion.Option options = 2

  Required. The list of allowed multiple choice options.

• bool has_other_option = 3

  When true, an additional option is presented to data collectors with the label "Other (specify)" or equivalent along with a short text field.

A single selectable multiple choice option.

Used in: MultipleChoiceQuestion

• string id = 1

  Required. The system-defined unique identifier of this entity.

• int32 index = 2

  Required. The index of the option when shown as a list.

• string label = 3

  The user-facing label of the option.

Valid values for the `type` field.

Used in: MultipleChoiceQuestion

• TYPE_UNSPECIFIED = 0

  Default value when no type is set/

• SELECT_ONE = 1

  Allow only one valid to be selected.

• SELECT_MULTIPLE = 2

  Allow one or more values to be selected.

A condition which passes if any of the specified values are selected.

Used in: Condition

• repeated string option_ids = 1

  Required. List of multiple choice option IDs which trigger the associated task. The task is shown if one or more of the related options are selected.

• string task_id = 2

  Required. The system-defined unique identifier of the task to which this MultipleChoiceSelection refers.

A question whose response is entered manually as a number.

Used in: Task

• NumberQuestion.Type type = 1

  Required. The type of number question.

Allowed values for the `type` field.

Used in: NumberQuestion

• TYPE_UNSPECIFIED = 0

  Type not specified.

• FLOAT = 1

  A number with a whole and optional decimal component.

A task in which the user must take a photo.

Used in: Task

• uint32 min_heading_degrees = 1

  Required. The minimum compass heading, in degrees, at which the photo may be captured. Use 0 with max. 360 to disable this constraint.

• uint32 max_heading_degrees = 2

  Required. The maximum compass heading, in degrees, at which the photo may be captured. Use 360 with min. 0 to disable this constraint.

A question whose response is entered manually as text.

Used in: Task

• TextQuestion.Type type = 1

  Required. The type of text question.

Valid values for the `type` field.

Used in: TextQuestion

• TYPE_UNSPECIFIED = 0

• SHORT_TEXT = 1

  A single line of text.

Data provided by data collectors for a specific task and LOI.

Used in: Submission

• string id = 1

  Required. A system-defined ID.

• string task_id = 2

  Required. ID of the task to which this task data refers.

• bool skipped = 3

  Indicates this task was skipped or left blank / unselected during data collection.

• oneof task_data_type

  User-provided data must be one of the following types:

  • TaskData.TextResponse text_response = 4

    A manually entered text response.

  • TaskData.NumberResponse number_response = 5

    A manually entered number response.

  • TaskData.DateTimeResponse date_time_response = 6

    A manually selected date and/or time response.

  • TaskData.MultipleChoiceResponses multiple_choice_responses = 7

    Response to a multiple-choice question.

  • TaskData.DrawGeometryResult draw_geometry_result = 8

    Result of data collector drawing a geometry (e.g., dropping a pin, drawing or walking a perimeter).

  • TaskData.CaptureLocationResult capture_location_result = 9

    The result of capturing the device's current fused location.

  • TaskData.TakePhotoResult take_photo_result = 10

    The result of a "take a photo" task.

The values returned by the data collector's device when completing a "capture location" task.

Used in: TaskData

• optional Coordinates coordinates = 1

  Required. The device's coordinates.

• double accuracy = 2

  The accuracy of `coordinates` returned by the device, in meters.

• double altitude = 3

  The altitude captured by the device.

• optional google.protobuf.Timestamp timestamp = 4

  Required. The time reported by the device when the location was captured.

A manually selected date and/or time response.

Used in: TaskData

• optional google.protobuf.Timestamp date_time = 1

  The date and/or time provided by the user. Date is set to UNIX epoch if unspecified (1970-01-01:00Z), time is set to 0:00:00.00.

Used in: TaskData

• optional Geometry geometry = 1

  The geometry provided by the data collector.

Used in: TaskData

• repeated string selected_option_ids = 1

  The unique IDs of options selected by the user.

• string other_text = 2

  The text provided in the "Other (please specify)" field, if present.

• bool other_selected = 3

  Indicate that the response has Other option selected.

A manually entered number response.

Used in: TaskData

• double number = 1

  The number provided by the user.

The result of a "take a photo" task.

Used in: TaskData

• string photo_path = 1

  Relative path of photo in remote storage.

A manually entered text response.

Used in: TaskData

• string text = 1

  The text provided by the user.