arcgis.apps.survey123 module

SurveyManager

class arcgis.apps.survey123.SurveyManager(gis, baseurl=None)

Bases: object

Survey Manager allows users and administrators of Survey 123 to analyze, report on, and access the data for various surveys.

get(survey_id)

returns a single Survey object from and Item ID or Item

property surveys

returns a list of existing Survey

Survey

class arcgis.apps.survey123.Survey(item, sm, baseurl=None)

Bases: object

A Survey is a single instance of a survey project. This class contains the Item information and properties to access the underlying dataset that was generated by the Survey form.

Data can be exported to Pandas DataFrames, shapefiles, CSV, and File Geodatabases.

In addition to exporting data to various formats, a Survey’s data can be exported as reports.

check_template_syntax(template_file=None)

A sync operation to check any syntax which will lead to a failure when generating reports in the given feature.

Parameter

Description

template_file

Required String. The report template file which syntax to be checked.

Returns

dictionary {Success or Failure}

create_report_template(template_type='individual', template_name=None, save_folder=None)

The create_report_template creates a simple default template that can be downloaded locally, edited and uploaded back up as a report template.

Parameter

Description

template_type

Optional String. Specify which sections to include in the template. Acceptable types are individual, summary, and summaryIndividual. Default is individual.

template_name

Optional String. Specify the name of the output template file without file extension.

save_folder

Optional String. Specify the folder location where the output file should be stored.

Returns

String

create_sample_report(report_template, where='1=1', utc_offset='+00:00', report_title=None, merge_files=None, survey_item=None, webmap_item=None, map_scale=None, locale='en', save_folder=None)

Similar task to generate_report for creating test sample report, and refining a report template before generating any formal report.

Parameter

Description

report_template

Required Item. The report template Item.

where

Optional String. This is the select statement used to export part or whole of the dataset. If the record count is > 1, then the item must be saved to your organization.

utc_offset

Optional String. This is the time offset from UTC to match the users timezone. Example: EST - “+04:00”

report_title

Optional String. An Item with this argument as the title if no save_folder argument. If save_folder argument is provided, this argument will be the name of the output file, or the base name for files in the output zipped package if the server-side component chose to zip up the output (depends upon the size and number of files that would result).

Note

If merge_files is either nextPage or continuous, report_title is the output file name.

merge_files

Optional String. Specify if output is a single file containing individual records on multiple pages (nextPage or continuous) or multiple files (none).

  • none - Print multiple records in split mode. Each record is a separate file. This is the default value.

  • nextPage - Print multiple records in a single document. Each record starts on a new page.

  • continuous - Print multiple records in a single document. EAch records starts on the same page of the previous record.

Note

A merged file larger than 500 MB will be split into multiple files.

save_folder

Optional String. Specify the folder location where the output file should be stored.

survey_item

Optional survey Item to provide additional information on the survey structure.

webmap_item

Optional Item . Specify the base map for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey.

map_scale

Optional Float. Specify the map scale when printing, the map will center on the feature geometry.

locale

Optional String. Specify the locale setting to format number and date values.

Returns

String

download(export_format, save_folder=None)

Exports the Survey’s data to other format

Parameter

Description

export_format

Required String. This is the acceptable export format that a user can export the survey data to. The following formats are acceptable: File Geodatabase, Shapefile, CSV, and DF.

save_folder

Optional String. Specify the folder location where the output file should be stored.

Returns

String or DataFrame

estimate(report_template, where='1=1')

An operation to estimate how many credits are required for a task with the given parameters.

Parameter

Description

report_template

Required Item . The report template Item.

where

Optional String. This is the select statement used to export part or whole of the dataset. If the filtered result has more than one feature/record, the request will be considered as a batch printing. Currently, one individual report will be generated for each feature/record.

Returns

dictionary {totalRecords, cost(in credits)}

generate_report(report_template, where='1=1', utc_offset='+00:00', report_title=None, package_name=None, output_format='docx', folder_id=None, merge_files=None, survey_item=None, webmap_item=None, map_scale=None, locale='en', save_folder=None)

The generate_report method allows users to create Microsoft Word and PDF reports from a survey using a report template. Reports are saved as an Item in an ArcGIS content folder or saved locally on disk. For additional information on parameters, see Create Report <https://developers.arcgis.com/survey123/api-reference/rest/report/#create-report>.

Note

The Survey123 report service may output one or more .docx or .pdf files, or a zipped package of these files. Whether the output is contained in a .zip file depends on the number of files generated and their size. For more information, see the packageFiles parameter in the Create Report documentation.

Note

To save to disk, do not specify a folder_id argument.

Parameter

Description

report_template

Required Item. The report template.

where

Optional String. The select statement issued on survey FeatureLayer to report on all survey records or a subset.

Query the parent_fl_url property of the Survey object to get the feature layer URL and retrieve a list of fields.

>>> gis = GIS(profile="your_profile")
>>> smgr = SurveyManager(gis)

>>> survey_item = gis.content.get("<survey form id>")
>>> survey_obj = smgr.get(survey_item.id)

>>> survey_fl = FeatureLayer(survey_obj.parent_fl_url, gis)

>>> print([f["name"] for f in survey_fl.properties.fields])

utc_offset

Optional String. Time offset from UTC. This offset is applied to all date, time, and dateTime questions that appear in the report output. Example: EST - “+04:00”

report_title

Optional String. If folder_id is provided, the result is an Item with this argument as the title. If save_folder argument is provided, this argument will be the name of the output file, or the base name for files in the output zipped package if the server-side component chose to zip up the output (depends upon the size and number of files that would result).

Note

If merge_files is either nextPage or continuous, report_title is the output file name.

package_name

Optional String. Specify the file name (without extension) of the packaged .zip file. If multiple files are packaged, the report_title argument will be used to name individual files in the package.

Note

The Survey123 report service automatically decides whether to package generated reports as a .zip file, depending on the output file count. See the packageFiles parameter description in the Create Report Request parameters documentation for details.

save_folder

Optional String. Specify the folder location where the output file or zipped file should be stored. If folder_id argument is provided, this argument is ignored.

output_format

Optional String. Accepts docx or pdf.

folder_id

Optional String. If a file Item is the desired output, specify the id value of the ArcGIS content folder.

merge_files

Optional String. Specify if output is a single file containing individual records on multiple pages (nextPage or continuous) or multiple files (none).

  • none - Print multiple records in split mode. Each record is a separate file. This is the default value.

  • nextPage - Print multiple records in a single document. Each record starts on a new page.

  • continuous - Print multiple records in a single document. EAch records starts on the same page of the previous record.

Note

A merged file larger than 500 MB will be split into multiple files.

survey_item

Optional survey Item to provide additional information on survey structure.

webmap_item

Optional web map Item. Specify the basemap for all map questions in the report. This takes precedence over the map set for each question in the report template.

map_scale

Optional Float. Specify the map scale for all map questions in the report. The map will center on the feature geometry. This takes precedence over the scale set for each question in the report template.

locale

Optional String. Specify the locale to format number and date values.

Returns

An Item or string upon completion of the reporting job. For details on the returned value, see Response Parameters for the generate_report() job.

 # Usage example #1: output a PDF file Item:
 >>> from arcgis.gis import GIS
 >>> from arcgis.apps.survey123 import SurveyManager

 >>> gis = GIS(profile="your_profile_name")

 >>> # Get report template and survey items
 >>> report_templ = gis.content.get("<template item id>")
 >>> svy_item = gis.content.get("<survey item id>")

 >>> svy_mgr = SurveyManager(gis)
 >>> svy_obj = svy_mgr.get(svy_item.id)

 >>> user_folder_id = [f["id"]
                      for f in gis.users.me.folders
                      if f["title"] == "folder_title"][0]

 >>> report_item = svy_obj.generate_report(report_template=report_templ,
                                           report_title="Title of Report Item",
                                           output_format="pdf",
                                           folder_id=user_folder_id,
                                           merge_files="continuous")

# Usage example #2: output a Microsoft Word document named `LessThan20_Report.docx`

>>> report_file = svy_obj.generate_report(report_template=report_templ,
                                          where="objectid < 20",
                                          report_title="LessThan20_Report",
                                          output_format="docx",
                                          save_folder="file\system\directory",
                                          merge_files="nextPage")

# Usage example #3: output a zip file named `api_gen_report_pkg.zip` of individual
#                   pdf files with a base name of `SpecimensOver30`

>>> report_file = svy_obj.generate_report(report_template=report_templ,
                                          where="number_specimens>30",
                                          report_title="SpecimensOver30",
                                          output_format="pdf",
                                          save_folder="file\system\directory",
                                          package_name="api_gen_report_pkg")
property properties

returns the properties of the survey

property report_templates

Returns a list of saved report items

Returns

list of Items

property reports

returns a list of generated reports

update_report_template(template_file=None)

Check report template syntax to identify any syntax which will lead to a failure when generating reports in the given feature and updates existing Report template Org item.

Parameter

Description

template_file

Required String. The report template file which syntax to be checked, and uploaded. The updated template name must match the name of the existing template item.

Returns

item {Success) or string (Failure}

upload_report_template(template_file=None, template_name=None)

Check report template syntax to identify any syntax which will lead to a failure when generating reports in the given feature. Uploads the report to the organization and associates it with the survey.

Parameter

Description

template_file

Required String. The report template file which syntax to be checked, and uploaded.

template_name

Optional String. If provided the resulting item will use the provided name, otherwise the name of the docx file will be used.

Returns

item {Success) or string (Failure}