# Command-line Tools
Source: https://docs.pingintel.com/command-line-tools
Ping offers Python-based command-line tools for interacting with the Ping API. They are Python-based,
so once you have a Python environment set up, simply install the library:
`pip install pingintel-api`
and set it up per the [documentation](https://pypi.org/project/pingintel-api/).
# Concepts & Identifiers
Source: https://docs.pingintel.com/concepts-and-identifiers
Shared terms and identifiers used across the Ping APIs
This page defines the terms and identifiers that recur across the Ping APIs. For how
these fit together when processing a document, see
[How Ping Processes SOVs](/how-ping-processes-sovs).
## Common terms
| Term | Meaning |
| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SOV** | Statement of Values. A spreadsheet listing insured locations and buildings with their values, construction details, and policy information. This is the input document you upload. |
| **SUD** | SOV Update Data. A revision applied to an existing SOV, carrying its own ID derived from the parent SOV ID. See [How SUDs work](/how-ping-processes-sovs#how-sov-updates-suds-work). |
| **`revision`** | Integer counting updates to an SOV. `0` is the original parse. Each SUD increments it. |
| **`record_type`** | Distinguishes records in [List Historical SOVs](/ping-extraction/get-sov-data/list-historical-sovs). `ORIG` is a newly parsed SOV. Any other value (for example `SCRUB` or `API`) is a SUD. |
| **`output_format`** | A file format generated from the Ping SOV, such as `JSON` or `AUDITOR`. Allowed values are gated by organization. Requests are case-insensitive. Discover the formats your account can use, and their canonical identifiers, with [List Available Output Formats](/ping-extraction/get-sov-data/list-available-output-formats). See [Output Formats](/output-formats) for the full reference. |
| **Output** | A generated file for one SOV or SUD in one format. Each output has a `filename` and a `url` you download with your API token. Outputs serve different purposes depending on the format. See [Outputter types](#outputter-types). |
| **Integrations** | Datasource codes, such as `PG` (Ping Geocoding) or `PH` (Ping Hazard), that enrich buildings with third-party data at parse or update time. Codes come from Ping.Data's [List Datasources](/ping-data/usage/list-datasources). See [Data Integrations](/integrations) for the attributes each source adds. |
| **Job** | An asynchronous unit of work, such as a parse, an update, or an output generation. Start it with a POST, then poll its status endpoint until `request.status` is `COMPLETE` or `FAILED`. |
## Outputter types
Ping produces many output formats, and your organization may have its own configured
beyond the public set. The formats your account can request, with their canonical
identifiers and labels, come from
[List Available Output Formats](/ping-extraction/get-sov-data/list-available-output-formats).
See [Output Formats](/output-formats) for the public reference. The categories below
group those formats by what they are for.
| Type | What it produces | Use it for |
| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| **Computer-readable formats** | Structured data for machine consumption: JSON, account and location files for catastrophe models such as AIR and RMS, and alternative encodings. | Feeding SOV data into your own systems. This is the primary path for integrations. |
| **Scrubbers** | Macro-enabled Excel workbooks (`.xlsm`) for reviewing and correcting the structured data Ping extracts. | Hands-on data entry and correction. A working artifact for getting the SOV right, not a final deliverable. |
| **Modelers** | Macro-enabled Excel workbooks (`.xlsm`) that update an SOV in place at the account and location level and run catastrophe tasks. | Brokers and underwriters adjusting already-extracted data, rather than first-pass correction. |
| **Auditor** | A read-only Excel workbook (`.xlsx`, no macros) with a summary view of the parsed data. | Reviewing scrubbing decisions without changing them. |
| **Marketing SOVs** | Presentation-ready Excel workbooks (`.xlsx`, no macros) in a co-branded layout with an organization's colors and preferences. | Sharing an SOV externally in a polished format. |
| **Partner import formats** | Exports that reshape Ping's data into the layout another system expects. | Handing SOV data to a carrier or downstream platform for direct import. |
| **Other** | Additional formats such as PowerPoint summaries and partner-specific CSV layouts. | Specialized delivery needs outside the categories above. |
Most of these formats, including organization-specific workbooks and partner exports,
are configured per account. Call
[List Available Output Formats](/ping-extraction/get-sov-data/list-available-output-formats)
to see the complete set you can request.
## Identifiers
Several identifiers move between requests as you work with the API. All of them are
strings. Unless the shape is documented below, treat the value as opaque — store it
and pass it back unchanged.
| Identifier | Example | Where you get it | Where you use it |
| :----------------- | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SOV ID (`sovid`) | `s-pl-ping-21nyms3` | Returned by [Start SOV Parsing Job](/ping-extraction/parse-sovs/start-sov-parsing-job) | Status checks, output downloads, update jobs, and history lookups for that SOV. |
| SUD ID (`sudid`) | `s-pl-ping-21nyms3-r001` | Returned by [Initiate SOV Update Job](/ping-extraction/update-sovs/initiate-sov-update-job) | Update status checks and output requests for that revision. Shape is the parent SOV ID plus `-r` and the zero-padded revision number. |
| Ping ID (`pingid`) | `p-mk-tempo-esw5ab` | Returned by Ping.Vision's [Initiate New Submission](/ping-vision/create-submission/initiate-new-submission) | Ping.Vision submission endpoints and events. Present on Extraction history records when a submission is involved. |
| `item_key` | `i-s-pl-ping-21nyms3!Sheet1!7` | `buildings[].item_key` in a JSON output | Identifies one building in an update CSV. Copy it verbatim from the output. |
| Output request ID | `9f4d8c10-3b7e-4a52-bd91-c823f15e4d76` | `request.id` in the [Get Or Create SOV Output](/ping-extraction/get-sov-data/get-or-create-sov-output) response | Polling [Get/Check SOV Output Result](/ping-extraction/parse-sovs/getcheck-sov-output-result). Cached responses carry an `immediately-done-` prefix. Use `request.status`, not the prefix, to detect completion. |
| `cursor_id` | — | List endpoints such as [List Historical SOVs](/ping-extraction/get-sov-data/list-historical-sovs) | Pass it back unchanged to fetch the next page. |
| `client_ref` | your own value | You choose it | Supplied when starting a parse or update job, returned on history records. |
`client_ref` is the one identifier you pick yourself. Pass a reference your system
can map back, such as your own submission key, when calling
[Start SOV Parsing Job](/ping-extraction/parse-sovs/start-sov-parsing-job) or
[Initiate SOV Update Job](/ping-extraction/update-sovs/initiate-sov-update-job).
[List Historical SOVs](/ping-extraction/get-sov-data/list-historical-sovs) returns it
on every record, which makes it the supported way to reconcile Ping activity against
your own records without storing a mapping of Ping IDs on your side.
# How Ping Processes SOVs
Source: https://docs.pingintel.com/how-ping-processes-sovs
High-level behavior of SOV processing in **Ping.Extraction**
**Ping.Extraction** turns a raw Statement of Values workbook into structured, normalized
building data, then generates that data in the output formats your organization uses.
This page explains the behavior behind that process: the lifecycle of a parsed SOV,
the status values you poll, how updates (SUDs) behave, and how to regenerate outputs
without re-uploading the source file. For the terms and identifiers used throughout,
see [Concepts & Identifiers](/concepts-and-identifiers). For step-by-step API call
sequences, see the workflows on the [Getting Started](/quickstart) page.
## How an input SOV becomes a Ping SOV
Parsing is asynchronous. One request starts the job, and everything after the upload
happens on Ping servers while you poll for completion.
1. **Upload.** Call
[Start SOV Parsing Job](/ping-extraction/parse-sovs/start-sov-parsing-job)
with the source file, a `document_type` of `SOV`, the `output_formats` you want
generated, and any `integrations` to apply. The response returns the SOV ID
immediately, before processing finishes. Save it. Every later request about this
SOV uses it.
2. **Identification and parsing.** Ping identifies the document type, locates the
building rows in the workbook, and maps the source columns onto standard Ping
attributes. The [JSON Format Specification](/json-formats/top-level) describes the
resulting structure, and [Buildings Attributes](/json-formats/buildings) covers the
per-building fields.
3. **Enrichment.** Requested integrations add third-party data, such as geocoding
results and hazard scores, to each building.
4. **Output generation.** Ping renders the normalized data into each requested format.
Formats you skip here can still be generated later. See
[Regenerating outputs](#regenerating-outputs).
5. **Completion.** Poll
[Check SOV Parsing Status](/ping-extraction/parse-sovs/check-sov-parsing-status)
until `request.status` is `COMPLETE` or `FAILED`. On success, `result.outputs`
lists each generated file with a `url`. Download them with
[Fetch Outputs of SOV Parsing Job](/ping-extraction/parse-sovs/fetch-outputs-of-sov-parsing-job).
Two behaviors worth knowing up front. Submitting the same file twice creates two
unrelated SOVs with two different IDs, so re-uploading is never the way to get fresh
outputs from an already-parsed SOV. The `id` inside a JSON output behaves
differently from the job IDs: it holds the parent SOV ID and keeps that value in
every regenerated output, so updating an SOV does not change the `id` in its JSON.
And the SOV ID is opaque. Its shape (`s-pl-ping-21nyms3`) is observable but not a
contract, so store it as a string and pass it through unchanged.
## Status values across endpoints
Every job moves through one lifecycle, but different endpoints encode it differently.
Job status endpoints —
[Check SOV Parsing Status](/ping-extraction/parse-sovs/check-sov-parsing-status)
and [Check SOV Update Status](/ping-extraction/update-sovs/check-sov-update-status) —
return full words in `request.status`.
[List Historical SOVs](/ping-extraction/get-sov-data/list-historical-sovs) returns
single-letter codes in `status`. The encodings map one to one:
| Lifecycle state | Job endpoints (`request.status`) | History (`status`) |
| :-------------- | :------------------------------- | :----------------- |
| Pending | `PENDING` | `P` |
| In progress | `IN_PROGRESS` | `I` |
| Enriching | `ENRICHING` | `E` |
| Re-enriching | `REENRICHING` | `R` |
| Complete | `COMPLETE` | `C` |
| Failed | `FAILED` | `F` |
`COMPLETE` and `FAILED` are the only terminal states. Poll until you see one of them
rather than matching the intermediate values, which can change as processing evolves.
List Historical SOVs only returns records that have already reached `C` or `F`, and
[Get/Check SOV Output Result](/ping-extraction/parse-sovs/getcheck-sov-output-result)
reports only `PENDING`, `COMPLETE`, and `FAILED`.
`result.status` is a separate axis. `request.status` tells you whether the job
finished, and `result.status` tells you how it ended. Parse jobs report `SUCCESS`,
`FAILED_TO_READ`, `PARTIAL_PARSE`, `FAILED_TO_PARSE`, or `FAILED_TO_PROCESS`. Update
jobs report `SUCCESS`, `FAILED_TO_PARSE`, or `FAILED_TO_PROCESS`. On failure,
`result.message` describes what went wrong.
## How SOV updates (SUDs) work
A SUD (SOV Update Data) is a revision of an existing SOV. Create one when you have
corrected building attributes, refreshed enrichments, or upstream data changes to
apply, and you want regenerated outputs without re-uploading the original workbook.
The [Update an SOV](/workflows/ping-extraction/update-sov) workflow walks through the
call sequence: initiate the update against the parent `sovid`, upload one or more
CSVs of revised attributes, then start the job.
When you use a SUD, expect the following behavior:
* **A SUD gets its own ID.** A SUD ID is the parent SOV ID plus `-r` and the
zero-padded revision number. Revision 1 of `s-pl-ping-21nyms3` is
`s-pl-ping-21nyms3-r001`, and revision 10 is `s-pl-ping-21nyms3-r010`. The
suffix always matches the record's `revision` value.
* **The parent SOV is preserved.** An update creates a new revision rather than
rewriting the original. The `revision` counter starts at `0` for the original parse
and increments with each SUD, and you can still request outputs for any earlier
revision. See [Regenerating outputs](#regenerating-outputs).
* **SUDs process like parse jobs.** The update runs asynchronously. Poll
[Check SOV Update Status](/ping-extraction/update-sovs/check-sov-update-status)
until `request.status` is `COMPLETE` or `FAILED`, then download the regenerated
files from `result.outputs`.
* **SUDs appear in account history.**
[List Historical SOVs](/ping-extraction/get-sov-data/list-historical-sovs)
returns SOVs and SUDs in one chronological stream. A `record_type` of `ORIG` marks
an original SOV, and any other value (for example `SCRUB` or `API`) marks a SUD.
* **Lineage is traceable.**
[Get Historical SOV](/ping-extraction/get-sov-data/get-historical-sov)
returns `original_sovid` and `previous_sovid`, which trace a SUD back through its
revision chain to the original SOV.
* **A SUD ID works where an SOV ID does for fetching outputs.** For example,
[Get Or Create SOV Output](/ping-extraction/get-sov-data/get-or-create-sov-output)
accepts either. When the path ID is a SUD ID, the `revision` parameter is ignored
because the SUD already identifies one specific revision.
## Regenerating outputs
A reoutput generates a new output file from an SOV that is already parsed. The source
file is not re-uploaded and the SOV ID does not change. There are two ways to get one,
and they answer different needs.
**You need a format you didn't request at parse time, or a fresh copy of an existing
file.** Call
[Get Or Create SOV Output](/ping-extraction/get-sov-data/get-or-create-sov-output).
If a matching output is already cached, the response returns it immediately with a
`request.status` of `COMPLETE`. Otherwise generation starts and you poll
[Get/Check SOV Output Result](/ping-extraction/parse-sovs/getcheck-sov-output-result)
with the returned request ID. Set `overwrite_existing` to `true` to discard the cached
file and force regeneration. Set `revision` to select which revision to read: `0` for
the original parse, a positive integer for that revision number, or `-1` (the default)
for the latest. The
[Get or Create an SOV Output](/workflows/ping-extraction/get-or-create-output)
workflow walks through this end to end.
**You want the SOV reprocessed with Ping's current processing.**
Initiate an update job with an `update_type` of `SCRUB`, as described in
[Update an SOV](/workflows/ping-extraction/update-sov), then start it. Uploading a
locations CSV is optional, so a `SCRUB` job can skip the add-locations step entirely.
To refresh third-party data, pass `integrations` when starting the job. When
`integrations` is omitted, your organization's workflow configuration determines
whether default enrichments run. The result is a new SUD, so you get a new revision
with regenerated outputs rather than a replacement file on the existing revision.
The difference in one line: Get Or Create SOV Output renders existing parsed data into
a file, while a `SCRUB` update reprocesses the data itself and creates a new revision.
# Data Integrations
Source: https://docs.pingintel.com/integrations
Ping supports multiple third-party data integrations which can be accessed programmatically via API requests. To retrieve data from specific integrations, include the `sources` parameter in the request payload and provide a list of integration codes corresponding to the desired sources.
## Integrations
* `PH - Ping Hazard`
* `LB - Lightbox`
* `PG - Ping Geocoding`
* `LBG - Lightbox Geocoding`
* *`full list coming soon...`*
## Base Output Attributes
The following attributes are always present in responses and provide metadata about the request/response transaction:
| **Data Element** | **Response Values** | **Description** |
| :------------------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| is\_success
(`boolean`) | Values
True, False
(`text`) | | Message returned when a request fails. |
| raw\_response
(`object`) | | The unprocessed response data from the datasource, preserved for debugging or advanced use cases. |
| persist\_for
(`object`) | | Duration for which this result should be cached before requiring a fresh fetch. |
| confidence
(`number`) | Values
0-100
(`number`) | | HTTP status code indicating the result of the request. See [https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) for reference. |
| fetch\_time
(`number`) | | Time taken to retrieve the data, in seconds. |
| is\_cache\_hit
(`boolean`) | Values
True, False
(`text`) | | Identifier of the worker process that handled this request. |
## Ping Hazard
**Code: PH**
The following attributes will be available in the `external_data` key of the response.
### Response Metadata
The following attributes describe the status, context, and quality of the hazard/risk data returned for the location.
| **Data Element** | **Response Values** | **Description** |
| :-------------------------------------------- | :------------------ | :--------------------------------------------------------------------------------------- |
| consulted\_
datasources
(`object`) | | List of data source codes used to generate the hazard and risk outputs for the location. |
| state
(`text`) | | The U.S. state where the location is found. |
| county
(`text`) | | Name of the county where the property is located. |
### Flood Data
The following attributes describe flood-related hazard exposure, proximity to the coast, FEMA flood classification, and surge modeling.
| **Data Element** | **Response Values** | **Description** |
| :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------- |
| fema\_flood\_zone\_
dfirm\_id
(`text`) | | FEMA Digital Flood Insurance Rate Map (DFIRM) panel identifier. |
| fema\_flood\_zone\_
version\_id
(`text`) | | Version identifier representing the specific FEMA flood zone data. |
| fema\_flood\_zone\_
version\_date
(`date`) | | Date of the FEMA flood zone data version used for this record. |
| fema\_flood\_zone
(`text`) | Values
A, AE, A1–A30, AO, AR, A99, V, VE, V1–V30, B, C, D, X
subtype
(`text`) | | Additional description on the features within the primary FEMA flood zone. |
| slosh\_zone\_category
(`number`) | Values
1-5
(`number`) | | Estimated storm surge height in feet for the associated SLOSH category. |
| distance\_to\_coast\_
miles
(`number`) | | Distance from the location to the coast, measured in miles. |
| distance\_to\_coast\_
feet
(`number`) | | Distance from the location to the coast, measured in feet. |
| distance\_to\_coast\_
closest\_point\_
longitude
(`number`) | | Longitude of the nearest point on the coast to the location. |
| distance\_to\_coast\_
closest\_point\_
latitude
(`number`) | | Latitude of the nearest point on the coast to the location. |
| distance\_to\_coast\_
connected\_lines
(`list[text]`) | | WKT LineString connecting the location to the nearest point on the coast. |
### Risk Data
The following attributes provide grade, numeric and textual ratings, and monetary values for different risk categories.
#### Composite
| **Data Element** | **Response Values** | **Description** |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| risk\_score
(`number`) | Values
0-100
(`currency`) | | Expected annual loss in USD used to derive the risk\_score percentile. |
| risk\_ratng
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for avalanche hazards. |
| avln\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for coastal flood hazards. |
| cfld\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for cold wave hazards. |
| cwav\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for drought hazards. |
| drgt\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for earthquake hazards. |
| erqk\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for hail hazards. |
| hail\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for heat wave hazards. |
| hwav\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for hurricane hazards. |
| hrcn\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for ice storm hazards. |
| istm\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for landslide hazards. |
| lnds\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for lightning hazards. |
| ltng\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for riverine flood hazards. |
| rfld\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for strong wind hazards. |
| swnd\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for tornado hazards. |
| trnd\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for tsunami hazards. |
| tsun\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for volcanic activity hazards. |
| vlcn\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`currency`) | | Expected annual loss in USD for wildfire hazards. |
| wfir\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`number`) | | Expected annual loss in USD for winter weather hazards. |
| wntw\_risks
(`number`) | Values
0-100
(`text`) | Values
Not Applicable, Very Low, Relatively Low, Relatively Moderate, Relatively High, Very High
(`percentage`) | Values
0.0-1.0
(`text`) | Values
P1, P2, P3, P4, U1, U2
class
(`number`) | Values
1-10
station\_feet
(`number`) | | Distance from the location to the nearest fire station, measured in feet. |
| distance\_to\_fire\_
hydrant\_feet
(`number`) | | Distance from the location to the nearest fire hydrant, measured in feet. |
| fire\_station\_point
(`text`) | | Geographic point representing the nearest fire station, in WKT format (e.g., POINT (longitude latitude)). |
| fire\_station\_closest\_
point\_longitude
(`number`) | | Longitude of the closest fire station to the property location. |
| fire\_station\_closest\_
point\_latitude
(`number`) | | Latitude of the closest fire station to the property location. |
| fire\_station\_extra\_
data
(`object`) | | Extra data about the nearest fire station, including name, address, geographic coordinates, city, state, zip code, and whether it is staffed by volunteers. |
| fire\_hydrant\_point
(`text`) | | Geographic point representing the nearest fire hydrant, in WKT format (e.g., POINT (longitude latitude)). |
| fire\_hydrant\_closest\_
point\_longitude
(`number`) | | Longitude of the closest fire hydrant to the property location. |
| fire\_hydrant\_closest\_
point\_latitude
(`number`) | | Latitude of the closest fire hydrant to the property location. |
### Crime Data
The following attributes describe crime statistics and safety metrics for the location.
| **Data Element** | **Response Values** | **Description** |
| :----------------------------------- | :---------------------------------------------- | :---------------------------------------------------- |
| total\_crime\_grade
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
(`text`) | Values
A-F
sinkhole\_feet
(`number`) | | Distance from the property to the nearest known Florida sinkhole, in feet. |
| florida\_sinkhole\_
point
(`text`) | | Geographic point representing the nearest known sinkhole in Florida, in WKT format (e.g., POINT (longitude latitude)). |
| florida\_sinkhole\_
closest\_point\_
longitude
(`number`) | | Longitude of the closest known sinkhole in Florida to the property location. |
| florida\_sinkhole\_
closest\_point\_
latitude
(`number`) | | Latitude of the closest known sinkhole in Florida to the property location. |
| florida\_sinkhole\_
extra\_data
(`object`) | | Extra data about the closest Florida sinkhole, including coordinates, event dates, geological characteristics, damage reports, and other sinkhole-specific data. |
### Elevation Data
The following attributes describe the elevation and topographic characteristics of the location.
| **Data Element** | **Response Values** | **Description** |
| :---------------------------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------- |
| elevation\_meters
(`number`) | | Elevation of the location above sea level, in meters. |
| resolution\_meters
(`number`) | | Size of each grid cell in the underlying risk data, in meters. Smaller values indicate higher spatial resolution. |
## Lightbox
**Code: LB**
The following attributes will be available in the `external_data` key of the response.
| **Data Element** | **Response Values** | **Description** |
| :----------------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------------------------------------------- |
| length\_units
(`text`) | | Units used for linear measurements (e.g., 'm'). |
| area\_units
(`text`) | | Units used to express area measurements (e.g., 'sqm'). |
| occupancy\_type
(`text`) | | Type of occupancy (e.g., 'SINGLE FAMILY RESIDENTIAL'). |
| land\_use\_category
(`text`) | | Use classification for the land (e.g., residential, commercial, agricultural). |
| bldg\_year\_built
(`year`) | | The year the building was originally constructed. |
| bldg\_year\_updated
(`year`) | | The most recent year in which the building was updated or modified. |
| construction\_type
(`text`) | | Category of building construction (e.g., wood frame, masonry, steel). |
| num\_stories
(`text`) | | Number of stories / floors in the building (as text). |
| num\_buildings
(`text`) | | The number of distinct buildings on the property (as text). |
| has\_basement
(`boolean`) | Values
True, False
gnd
(`number`) | | How many levels / floors are below ground (basement levels). |
| num\_stories\_desc
(`text`) | | Description of the number of stories (e.g., '2+B'). |
| bldg\_area
(`number`) | | The building's footprint / gross floor area (in area units). |
| wall\_type
(`text`) | | Wall construction type (e.g., masonry, wood frame). |
| roof\_covering
(`text`) | | Material used for the roof covering (e.g., 'ASPHALT'). |
| roof\_covering\_code
(`text`) | | Code representing the roof covering material. (e.g., 'P') |
| roof\_type
(`text`) | | The structural type of roof (e.g., gable, flat, hip). |
| lot\_size
(`number`) | | Size of the land / parcel (in area units). |
| assessed\_value\_total
(`currency`) | | Total assessed value of the property. |
| assessed\_value\_land
(`currency`) | | Assessed value of the land portion of the property. |
| assessed\_value\_
improvements
(`currency`) | | Assessed value of improvements (structures) on the property. |
| assessed\_value\_year
(`year`) | | The year for which the assessed value applies. |
| market\_value\_total
(`currency`) | | Market valuation of the property. |
| market\_value\_land
(`currency`) | | Market value of the land portion of the property. |
| market\_value\_
improvements
(`currency`) | | Market value of improvements (structures) on the property. |
| market\_value\_year
(`year`) | | The year for which the market value is estimated. |
| bedrooms
(`number`) | | Number of bedrooms. |
| baths
(`number`) | | Number of bathrooms. |
| ownership\_status\_
code
(`text`) | | Code for ownership status (e.g., 'CO'). |
| ownership\_status\_
code\_desc
(`text`) | | Description corresponding to the ownership status code (e.g., 'COMPANY' or 'CORPORATION'). |
| owner\_names
(`list[text]`) | | List of owner names. |
| owner\_street
(`text`) | | Street address of the owner. |
| owner\_city
(`text`) | | City of the property owner's address. |
| owner\_state
(`text`) | | State in the owner's address. |
| owner\_zip
(`text`) | | ZIP code of the owner's address. |
| owner\_occupied
(`boolean`) | Values
True, False
(`text`) | | Description of the heating system (e.g., 'FORCED AIR UNIT'). |
| heating\_code
(`text`) | | Code for the type of heating system installed. |
| air\_conditioning\_
desc
(`text`) | | A textual description of the air conditioning type (e.g., 'Central / Forced air'). |
| air\_conditioning\_
code
(`text`) | | A code representing the type of air conditioning installed (if any). |
| valuation\_model\_
value
(`currency`) | | Valuation or predictive value of the property from LightBox's model. |
| valuation\_model\_
value\_high
(`currency`) | | Upper bound of the modeled value (confidence interval). |
| valuation\_model\_
value\_low
(`currency`) | | Lower bound of the modeled value (confidence interval). |
| valuation\_model\_
value\_score
(`number`) | Values
0-100
(`text`) | | Street address of the property. |
| city
(`text`) | | The city or municipality where the property is located. |
| state
(`text`) | | The U.S. state where the location is found. |
| zip
(`text`) | | ZIP code of the property location. |
| country
(`text`) | | Country where the property is located. |
| latitude
(`number`) | | Latitude coordinate of the property. |
| longitude
(`number`) | | Longitude coordinate of the property. |
| transaction\_price\_
per\_area
(`currency`) | | The sale price of the property divided by its area. |
| transaction\_value
(`currency`) | | The total dollar amount paid in the most recent recorded sale of the property. |
| transaction\_date
(`date`) | | The official recorded date of the most recent property sale or transfer. |
| h3
(`text`) | | H3 geospatial index of the property location. |
## Ping Geocoding
**Code: PG**
The following attributes will be available in the `location_data` key of the response.
| **Data Element** | **Response Values** | **Description** |
| :------------------------------------------------------------------ | :------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| street\_number
(`text`) | | Street number component of the address. |
| route
(`text`) | | Street name or route component of the address. |
| location\_type
(`text`) | | Indicates how precisely the coordinates represent the actual address (e.g., 'ROOFTOP') |
| latitude
(`number`) | | Latitude of the location. |
| longitude
(`number`) | | Longitude of the location. |
| formatted\_address
(`text`) | | Human-readable full address (e.g., '123 Main St, Miami, FL 33133'). |
| address\_line\_1
(`text`) | | Primary street address line of the location (e.g., '123 Main St'). |
| address\_line\_2
(`text`) | | Secondary address information of the location (e.g., Apt. 33) |
| city
(`text`) | | City where the property is located (e.g., 'Miami'). |
| postal\_code
(`text`) | | Postal code (e.g., ZIP code in the US). |
| county
(`text`) | | County or equivalent region for the location (e.g., 'Miami-Dade'). |
| state
(`text`) | | State abbreviation (e.g., 'MA'). |
| country
(`text`) | | Country where the property is located (e.g., 'US'). |
| precision
(`number`) | Values
0-100
(`text`) | | Full state name. |
| state\_code
(`text`) | | Alternate field for state abbreviation. |
| country\_subdivision\_
name
(`text`) | | Full name of the state/province (e.g., 'Florida'). |
| country\_subdivision\_
code
(`text`) | | Abbreviated code for the state/province (e.g., 'FL'). |
| source\_desc
(`text`) | | Source system that provided the geocoded data. |
| consulted\_
datasources
(`list[text]`) | | List of data source codes used to generate the address result. |
| version
(`text`) | | Data source version identifier (e.g., '2.1'). |
| candidate\_countries
(`list[text]`) | | |
| match\_level
(`text`) | | Level of detail matched in the address (e.g., 'street\_imputed'). |
| precision\_
confidences
(`object`) | | Map of precision scores to confidence values. |
| match\_confidence
(`number`) | Values
0.0-1.0
(`text`) | | The fully assembled address string built from the individual address components. |
| used\_point\_
coordinates\_from\_
input
(`boolean`) | Values
True, False
The following attributes will be available in the `location_data` key of the response.
| **Data Element** | **Response Values** | **Description** |
| :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| street\_number
(`text`) | | Street number component of the address. |
| route
(`text`) | | Street name or route component of the address. |
| location\_type
(`text`) | | Indicates how precisely the coordinates represent the actual address (e.g., 'ROOFTOP') |
| latitude
(`number`) | | Latitude of the location. |
| longitude
(`number`) | | Longitude of the location. |
| formatted\_address
(`text`) | | Human-readable full address (e.g., '123 Main St, Miami, FL 33133'). |
| address\_line\_1
(`text`) | | Primary street address line of the location (e.g., '123 Main St'). |
| address\_line\_2
(`text`) | | Secondary address information of the location (e.g., Apt. 33) |
| city
(`text`) | | City where the property is located (e.g., 'Miami'). |
| postal\_code
(`text`) | | Postal code (e.g., ZIP code in the US). |
| county
(`text`) | | County or equivalent region for the location (e.g., 'Miami-Dade'). |
| state
(`text`) | | State abbreviation (e.g., 'MA'). |
| country
(`text`) | | Country where the property is located (e.g., 'US'). |
| precision
(`number`) | Values
0-100
(`text`) | | Full state name. |
| state\_code
(`text`) | | Alternate field for state abbreviation. |
| country\_subdivision\_
name
(`text`) | | Full name of the state/province (e.g., 'Florida'). |
| country\_subdivision\_
code
(`text`) | | Abbreviated code for the state/province (e.g., 'FL'). |
| score
(`number`) | | Overall confidence score for the geocoding match. |
| street\_number\_score
(`number`) | | Confidence score for the street number component match. |
| route\_score
(`number`) | | Confidence score for the street name/route component match. |
| address\_line\_1\_score
(`number`) | | Confidence score for the primary address line match. |
| city\_score
(`number`) | | Confidence score for the city/locality component match. |
| postal\_code\_score
(`number`) | | Confidence score for the postal code component match. |
| address\_id
(`text`) | | Unique Lightbox identifier for the geocoded address. |
| parcel\_id
(`text`) | | Unique Lightbox identifier for the parcel associated with the address. |
| assessment\_id
(`text`) | | Unique Lightbox identifier for the tax assessment record associated with the address. |
| structure\_id
(`text`) | | Unique Lightbox identifier for the structure/building at the address. |
| precision\_code
(`number`) | Values
[Precision Code List](https://lightbox.document360.io/docs/geocode-precision-code)