> ## Documentation Index > Fetch the complete documentation index at: https://docs.pingintel.com/llms.txt > Use this file to discover all available pages before exploring further. # List SOV locations > List the locations of an SOV or portfolio that match the filters, one page at a time. Page with `limit` and `offset`, or follow `next` until it is null. ## OpenAPI ````yaml https://api.sovfixer.com/api/schema/?format=json get /api/v1/sov/{id}/locations openapi: 3.0.3 info: title: Ping.Extraction API version: v1.0 description: >- ### Ping.Extraction API This API provides an asynchronous method for parsing Excel SOV documents using the Ping Intel SOV Fixer platform. The typical SOV Fixer usage flow is: * POST to `/api/v1/sov` * Poll GET `/api/v1/sov/{id}`, passing the `id` given by the previous response until `response.request.status` is `COMPLETE` or `FAILED`. Depending on load, number of buildings in the SOV, and 3rd party integrations, it may take anywhere from a few seconds to many minutes. * Download the parsed SOV data as JSON from `/api/v1/sov/{id}/output/{filename}`. The exact url comes from the response to the above query, in `response.result.outputs[].url`. API Usage Examples: [Python](/api/v1/sov-api-usage-example.py) | [.NET](/api/v1/sov-api-usage-example.cs) Client Libraries: [Python](https://pypi.org/project/pingintel-api/) #### Authorization Most endpoints are protected by Bearer authentication. Under each endpoint listed below, click into the `authorizations` section to see what is required for that endpoint. #### Output JSON Example: ```json { "id": "s-e-xxxxxxx", "source_filename": "My Example SOV.xls", "num_buildings": 26, "extra_data": { "insured_name": "Joe Insured", "... custom document-level data fields ...": "" }, "buildings": [ { "item_key": "i-s-e-xxxxxxx!Original SOV Sheet!7", "building_counter": 1, "sheet_name": "Original SOV Sheet", "sheet_row_number": 7, "parsing_sheet_name": "Original SOV Sheet", "location_code": { "value": "A-1", "confidence": 0.5, "comment": "Adjusted." }, "bldg_name": { "value": "Elementary School", "confidence": 0.7 }, "street": { "value": "1212 Mockingbird Lane", "confidence": 0.7 }, "city": { "value": "Tewksbury", "confidence": 0.5 }, "state": { "original": "Mass", "value": "MA", "confidence": 0.9 }, "zip": { "value": "01876", "original": 1876, "confidence": 0, "comment": "Please check." }, "... more building attributes ...": "", "external_data": { "PG": { "latitude": 42.6109, "longitude": -71.2342, "confidence": 0.9, "street": "1212 Mockingbird Ln", "city": "Tewksbury", "... rest of the data from the Ping Geocoding (PG) external data source ...": "" }, "... any other requested third party data sources ...": "" }, "extra": { "... columns that were not identified as a standard SOV field ...": "", "Unidentified Column": "123213", "Another Unidentified Column": "abc" } }, "... additional buildings ...": "" ] } ``` Complete JSON reference documentation can be found for each output type: [SOV](/docs/data/SOV/) | [Premium BDX](/docs/data/PREM_BDX/) | [Claim BDX](/docs/data/CLAIM_BDX/). Some notes about specific JSON output fields: * `limits__total_limit`: Contains the TIV if explicitly specified in the SOV. If not, it is summed from the fields `limits__building_limit` + `limits__bpp_limit` + `limits__bi_limit` + `limits__signs_and_other_limit`. * `limits__building_limit`: Building Limit is an aggregate of: * `limits__building_value` * `limits__location_limit` * `limits__blanket_limit` * `limits__building_only_limit` * `limits__real_property_limit` * `limits__structure_limit` * `limits__bpp_limit`: Business Personal Property (Contents) Limit is an aggregate of: * `limits__contents_value` * `limits__contents_limit` * `limits__bpp_value` * `limits__equip_limit` * `limits__personal_property_limit` * Any field identified as a limit field but not otherwise categorized. * `limits__bi_limit`: Business Interruption Limit is an aggregate of: * `limits__bi_value` * `limits__bi_income_limit` * `limits__business_interruption_limit` * `limits__time_element_limit` * `limits__signs_and_other_limit`: Signs and Other Structures Limit is an aggregate of: * `limits__signs_limit` * `limits__other_structures_limit` ### Ping Intel SOV History API This API provides a method for accessing historical SOV submissions including their revisions (SOV Updates) and the raw parsed output. The typical usage workflow is: * GET to `api/v1/sov/history?start={start_timestamp}` for a list of SOVIDs submitted between `start_timestamp` and now. * For each sovid: * GET to `api/v1/sov/history/{id}` to get information about the SOV or SOV Update. This includes any output we produced in servicing the request * GET to the the URL in the outputs dict to download the resource you need. contact: email: support@pingintel.com name: Ping Intel url: https://www.pingintel.com servers: - url: https://api.sovfixer.com description: Ping.Extraction API - url: https://api-staging.sovfixer.com description: Ping.Extraction API (staging) security: [] tags: - name: Parse SOVs - name: Get SOV Data - name: Analyze SOVs description: > Totals, value distributions, location lists, an exposure report and a layer analysis for the locations of an SOV or portfolio, narrowed by location filters. **How filters combine** - Different fields: a location must match all of them. - Repeating an array field (`state=TX&state=FL`): matches any of the values. - Several operators on one field (`const__bldg_year_built[gte]=1990&const__bldg_year_built[lt]=2000`): all must hold, forming a range. - `[bins]` with several bins: matches any of them. - `[not_in]`: excludes those values; locations missing the field are excluded too. - `[gt_or_null]`, `[gte_or_null]`, `[lte_or_null]`: the comparison holds or the value is missing. - `N/A` as an exact value: matches locations missing the field. - An exact value, `[bins]` and range operators cannot be combined on one field; the request returns 400. - A report row's `filter` has the same shape: send it as query parameters, or follow the row's `links`, to drill into that row. Example: `state=TX&state=FL&const__bldg_year_built[gte]=1990&const__bldg_year_built[lt]=2000&county[not_in]=Harris` selects locations in Texas or Florida, built from 1990 through 1999, outside Harris County. x-operation-order: - get_sov_summary - list_sov_locations - get_sov_exposure_report - get_sov_layer_analysis - name: Update SOVs paths: /api/v1/sov/{id}/locations: get: tags: - Analyze SOVs summary: List SOV locations description: >- List the locations of an SOV or portfolio that match the filters, one page at a time. Page with `limit` and `offset`, or follow `next` until it is null. operationId: list_sov_locations parameters: - in: path name: id schema: type: string description: pingid, sovid, or portfolio id required: true - in: query name: filters schema: $ref: '#/components/schemas/SOVAnalyticsFiltersRequest' description: >- Location filters. Send each field as its own query parameter: `field=value` for an exact match, `field[op]=value` for an operator. `state=TX&state=FL&const__bldg_year_built[gte]=1990` selects locations in TX or FL built in 1990 or later. - Different fields: a location must match all of them. - Repeating a field, or `[bins]` with several bins: matches any of the values. - Several operators on one field: all must hold, forming a range. - `N/A` as an exact value: matches locations missing the field. - A field takes an exact value, `[bins]` or range operators, not a mix. See [SOV Data Analysis](https://docs.pingintel.com/sov-data-analysis) for every rule and examples. explode: true style: form - in: query name: layer_attach schema: type: integer default: 0 description: >- Layer attachment point. With `layer_limit`, defines the layer whose per-location exposure is reported as `limits__total_limit_in_layer`. Defaults to 0. - in: query name: layer_limit schema: type: integer description: >- Layer limit. With `layer_attach`, defines the layer whose per-location exposure is reported as `limits__total_limit_in_layer`. Omit for a layer with no upper limit. - in: query name: limit schema: type: integer maximum: 1000 minimum: 1 default: 100 description: Maximum number of locations to return, up to 1000. Defaults to 100. - in: query name: offset schema: type: integer minimum: 0 default: 0 description: >- Number of locations to skip before the first one returned. Defaults to 0. - in: query name: sort schema: enum: - '-limits__total_limit' - limits__total_limit - building_counter - '-building_counter' type: string x-spec-enum-id: d810cd08ee3449ca default: '-limits__total_limit' description: >- Sort order. A leading `-` sorts descending. Portfolios sort by member SOV first. Defaults to `-limits__total_limit`. * `-limits__total_limit` - -limits__total_limit * `limits__total_limit` - limits__total_limit * `building_counter` - building_counter * `-building_counter` - -building_counter responses: '200': content: application/json: schema: $ref: '#/components/schemas/SOVLocationListResponse' examples: LargestLocationsFirst: value: count: 148 next: >- https://api.sovfixer.com/api/v1/sov/s-e-c2qahx/locations?limit=2&offset=2&sort=-limits__total_limit previous: null results: - sovid: s-e-c2qahx item_key: i-s-e-c2qahx!Locations!12 building_counter: 6 bldg_name: Brickell Tower street: 1101 Brickell Ave city: Miami county: Miami-Dade state: FL zip: '33131' country: US latitude: 25.7637 longitude: -80.1912 geocode_match_level: point limits__total_limit: 41500000 limits__building_limit: 33000000 limits__bpp_limit: 5500000 limits__bi_limit: 3000000 limits__signs_and_other_limit: 0 const__code_iso: 6 const__code_air: 131 const__code_rms: '3' occupancy__code_air: 315 occupancy__code_atc: 8 const__bldg_year_built: 2008 const__num_stories: 32 const__bldg_area_sqft: 410000 - sovid: s-e-c2qahx item_key: i-s-e-c2qahx!Locations!31 building_counter: 25 bldg_name: null street: 9800 Northwest Fwy city: Houston county: Harris state: TX zip: '77092' country: US latitude: 29.8125 longitude: -95.4703 geocode_match_level: point limits__total_limit: 26800000 limits__building_limit: 19000000 limits__bpp_limit: 4800000 limits__bi_limit: 3000000 limits__signs_and_other_limit: 0 const__code_iso: 4 const__code_air: 111 const__code_rms: 2C1 occupancy__code_air: 312 occupancy__code_atc: 5 const__bldg_year_built: 1994 const__num_stories: 2 const__bldg_area_sqft: 185000 summary: Largest locations first description: One page of matching locations. '202': content: application/json: schema: $ref: '#/components/schemas/SOVAnalyticsNotReady' description: Analytics for this SOV are still being built. Retry later. '400': content: application/json: schema: type: object additionalProperties: type: array items: type: string description: Error messages keyed by query parameter name. description: A query parameter is invalid or unknown. '401': content: application/json: schema: $ref: '#/components/schemas/SOVAnalyticsError' description: Credentials are missing or invalid. '403': content: application/json: schema: $ref: '#/components/schemas/SOVAnalyticsError' description: The SOV or portfolio does not exist, or the caller cannot view it. '404': content: application/json: schema: $ref: '#/components/schemas/SOVAnalyticsError' description: >- `id` is a pingid that matches no submission or whose submission has no SOV yet, or no analytics exist for the SOV yet. Requesting its `summary` starts building them. '409': content: application/json: schema: $ref: '#/components/schemas/SOVAnalyticsError' description: Analytics for this SOV failed to build. security: - tokenAuth: [] - cookieAuth: [] components: schemas: SOVAnalyticsFiltersRequest: type: object description: >- Location filters. Each key is a field: give a value for an exact match, or an object of operators. additionalProperties: false properties: bounding_polygon: type: string description: >- Polygon enclosing the locations to include, as comma-separated points `lat1,lng1,lat2,lng2,...`. 3 to 100 points; the ring closes automatically. cape_roof_condition_score: type: array items: type: string description: >- CAPE Analytics roof condition ratings to include, e.g. `-1` (poor) or `-2` (severe). cfld_alrb_score_catg: type: array items: type: string description: >- National Risk Index coastal flooding annualized loss rate categories to include, e.g. `High`. const__bldg_area: description: >- Building area in square feet. `N/A` selects locations without one. Operators: `gte`, `gt`, `lte`, `lt`, `lte_or_null`. anyOf: - type: string description: >- Building area in square feet. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: gt: type: integer description: Minimum, exclusive. gte: type: integer description: Minimum, inclusive. lt: type: integer description: Maximum, exclusive. lte: type: integer description: Maximum, inclusive. lte_or_null: type: integer description: Maximum, inclusive; also matches missing values. const__bldg_year_built: description: >- Year built. `N/A` selects locations without one. Operators: `gte`, `gt`, `lte`, `lt`, `lte_or_null`, `bins`. anyOf: - type: string description: Year built. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: bins: type: array items: enum: - Pre-1972 - 1972 - 1994 - 1995 - 2001 - 2001+ type: string description: |- * `Pre-1972` - Pre-1972 * `1972 - 1994` - 1972 - 1994 * `1995 - 2001` - 1995 - 2001 * `2001+` - 2001+ x-spec-enum-id: 12abda2246940686 description: >- Includes these bins: `Pre-1972`, `1972 - 1994`, `1995 - 2001`, `2001+`. gt: type: integer description: Minimum, exclusive. gte: type: integer description: Minimum, inclusive. lt: type: integer description: Maximum, exclusive. lte: type: integer description: Maximum, inclusive. lte_or_null: type: integer description: Maximum, inclusive; also matches missing values. const__code_air: type: array items: type: integer description: AIR construction codes to include. const__code_iso: type: array items: type: string description: ISO construction classes to include. const__code_rms: type: array items: type: string description: RMS construction codes to include. const__iso_protection_class: description: >- ISO protection class. `N/A` selects locations without one. Operators: `gt`. anyOf: - type: string description: ISO protection class. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: gt: type: integer description: Minimum, exclusive. const__num_stories: description: >- Number of stories. `N/A` selects locations without one. Operators: `gte`, `gt`, `lte`, `lt`. anyOf: - type: string description: Number of stories. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: gt: type: integer description: Minimum, exclusive. gte: type: integer description: Minimum, inclusive. lt: type: integer description: Maximum, exclusive. lte: type: integer description: Maximum, inclusive. const__roof_year_updated: description: 'Roof year updated. Operators: `lte_or_null`.' anyOf: - type: string description: Roof year updated. - type: object title: operators additionalProperties: false properties: lte_or_null: type: integer description: Maximum, inclusive; also matches missing values. const_code_pcg: description: >- Ping construction classes to include, e.g. `WF`, `JM`, `RC`. `N/A` selects locations without one. Operators: `not_in`. anyOf: - type: array items: type: string description: >- Ping construction classes to include, e.g. `WF`, `JM`, `RC`. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. country: description: 'Country codes to include, e.g. `US`. Operators: `not_in`.' anyOf: - type: array items: type: string description: Country codes to include, e.g. `US`. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. county: description: 'County names to include, e.g. `Harris`. Operators: `not_in`.' anyOf: - type: array items: type: string description: County names to include, e.g. `Harris`. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. distance_to_coast_miles: description: >- Distance to the coast, in miles. Operators: `gt`, `gte`, `lt`, `lte`, `gt_or_null`, `gte_or_null`, `lt_or_null`, `lte_or_null`. anyOf: - type: number format: double minimum: 0 description: Distance to the coast, in miles. - type: object title: operators additionalProperties: false properties: gt: type: number format: double description: Minimum, exclusive. gt_or_null: type: number format: double description: Minimum, exclusive; also matches missing values. gte: type: number format: double description: Minimum, inclusive. gte_or_null: type: number format: double description: Minimum, inclusive; also matches missing values. lt: type: number format: double description: Maximum, exclusive. lt_or_null: type: number format: double description: Maximum, exclusive; also matches missing values. lte: type: number format: double description: Maximum, inclusive. lte_or_null: type: number format: double description: Maximum, inclusive; also matches missing values. eq_zone: type: array items: type: string description: >- Earthquake zones to include: `CA`, `PacNW`, `New Madrid`, `HI` or `AK`. fema_flood_zone: description: >- FEMA flood zone, e.g. `AE`. `N/A` selects locations without one. Operators: `bins`. anyOf: - type: string description: FEMA flood zone, e.g. `AE`. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: bins: type: array items: enum: - SFHA - Non-SFHA type: string description: |- * `SFHA` - SFHA * `Non-SFHA` - Non-SFHA x-spec-enum-id: 96b50cfc0de3290d description: 'Includes these bins: `SFHA`, `Non-SFHA`.' hail_alrb_score_catg: type: array items: type: string description: >- National Risk Index hail annualized loss rate categories to include, e.g. `High`. hail_riskr: type: array items: type: string description: National Risk Index hail risk ratings to include, e.g. `Very High`. lat1: type: number format: double maximum: 90 minimum: -90 description: >- North latitude of the bounding box. Supply with `lat2`, `lng1` and `lng2`. lat2: type: number format: double maximum: 90 minimum: -90 description: South latitude of the bounding box. limits__total_limit: description: >- Location TIV: `limits__total_limit`, the sum of the building, BPP, BI and signs-and-other limits. Operators: `gte`, `gt`, `lte`, `lt`. anyOf: - type: integer description: >- Location TIV: `limits__total_limit`, the sum of the building, BPP, BI and signs-and-other limits. - type: object title: operators additionalProperties: false properties: gt: type: integer description: Minimum, exclusive. gte: type: integer description: Minimum, inclusive. lt: type: integer description: Maximum, exclusive. lte: type: integer description: Maximum, inclusive. lng1: type: number format: double maximum: 180 minimum: -180 description: >- West longitude of the bounding box. A value greater than `lng2` crosses the antimeridian. lng2: type: number format: double maximum: 180 minimum: -180 description: East longitude of the bounding box. occupancy__code_air: type: array items: type: integer description: AIR occupancy codes to include. occupancy__code_atc: type: array items: type: string description: ATC occupancy codes to include. occupancy__desc_air: description: >- AIR occupancy descriptions to include. `N/A` selects locations without one. Operators: `not_in`. anyOf: - type: array items: type: string description: >- AIR occupancy descriptions to include. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. occupancy__desc_atc: description: >- ATC occupancy descriptions to include. `N/A` selects locations without one. Operators: `not_in`. anyOf: - type: array items: type: string description: >- ATC occupancy descriptions to include. `N/A` selects locations without one. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. ping_geo__match_level: description: >- Geocode match levels to include, e.g. `point`. `N/A` selects locations without a geocode. Operators: `not_in`. anyOf: - type: array items: type: string description: >- Geocode match levels to include, e.g. `point`. `N/A` selects locations without a geocode. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. protect__pct_sprinklered: type: array items: enum: - 100% - Partial - 0% - N/A type: string description: |- * `100%` - 100% * `Partial` - Partial * `0%` - 0% * `N/A` - N/A x-spec-enum-id: 559519371c31f809 description: >- Sprinkler coverages to include: `0%`, `Partial` (above 0% and below 100%), `100%`, or `N/A` (unknown, or outside 0% to 100%). scs_roof_age: type: array items: type: string description: >- Roof age cutoff year: selects locations whose roof was last updated before it (or, without a roof year, built before it) and locations with neither year. slosh_zone: type: array items: type: integer description: SLOSH storm surge hurricane categories (1-5) to include. state: description: 'State or province codes to include, e.g. `TX`. Operators: `not_in`.' anyOf: - type: array items: type: string description: State or province codes to include, e.g. `TX`. - type: object title: operators additionalProperties: false properties: not_in: type: array items: type: string description: Excludes these values. total_crime_grade: type: array items: type: string description: Crime grades to include, `A` (minimal) to `F` (high). trnd_alrb_score_catg: type: array items: type: string description: >- National Risk Index tornado annualized loss rate categories to include, e.g. `High`. trnd_riskr: type: array items: type: string description: >- National Risk Index tornado risk ratings to include, e.g. `Very High`. wfir_alrb_score_catg: type: array items: type: string description: >- National Risk Index wildfire annualized loss rate categories to include, e.g. `High`. wfir_riskr: type: array items: type: string description: >- National Risk Index wildfire risk ratings to include, e.g. `Very High`. wind_tier: type: array items: type: string description: >- Hurricane wind tiers to include: `Tier 1`, `Tier 2`, `Tri-County`, `All Other FL` or `Harris County, TX`. SOVLocationListResponse: type: object properties: count: type: integer description: Total number of matching locations. next: type: string format: uri nullable: true description: URL of the next page. Null on the last page. previous: type: string format: uri nullable: true description: URL of the previous page. Null on the first page. results: type: array items: $ref: '#/components/schemas/SOVLocation' description: Locations on this page. required: - count - next - previous - results SOVAnalyticsNotReady: type: object properties: pct_complete: type: integer description: Build progress, 0-100. status: enum: - NOT_INITIALIZED - INITIALIZING type: string x-spec-enum-id: ac0132187203409c description: |- Analytics build status. * `NOT_INITIALIZED` - NOT_INITIALIZED * `INITIALIZING` - INITIALIZING required: - pct_complete - status SOVAnalyticsError: type: object properties: detail: type: string description: Error message. required: - detail SOVLocation: type: object properties: bldg_name: type: string nullable: true description: Building name. building_counter: type: integer description: >- Location number within its SOV. Repeats across a portfolio's member SOVs. city: type: string nullable: true description: City. const__bldg_area_sqft: type: integer nullable: true description: Building area in square feet. const__bldg_year_built: type: integer nullable: true description: Year built. const__code_air: type: integer nullable: true description: AIR construction code. const__code_iso: type: integer nullable: true description: ISO construction code. const__code_rms: type: string nullable: true description: RMS construction code. const__num_stories: type: number format: double nullable: true description: Number of stories. country: type: string nullable: true description: Country code. county: type: string nullable: true description: County. geocode_match_level: type: string nullable: true description: Geocode match level, e.g. `point`. Null when not geocoded. item_key: type: string description: Stable location identifier. latitude: type: number format: double nullable: true description: Latitude. Null when not geocoded. limits__bi_limit: type: number nullable: true description: Business interruption limit. limits__bpp_limit: type: number nullable: true description: Business personal property (BPP) limit. limits__building_limit: type: number nullable: true description: Building limit. limits__signs_and_other_limit: type: number nullable: true description: Signs and other structures limit. limits__total_limit: type: number nullable: true description: >- Total limit (TIV): the sum of the building, BPP, BI and signs-and-other limits. longitude: type: number format: double nullable: true description: Longitude. Null when not geocoded. occupancy__code_air: type: integer nullable: true description: AIR occupancy code. occupancy__code_atc: type: integer nullable: true description: ATC occupancy code. sovid: type: string description: SOV id of the policy the location belongs to. state: type: string nullable: true description: State or province code. street: type: string nullable: true description: Street address. zip: type: string nullable: true description: Postal code. required: - bldg_name - building_counter - city - const__bldg_area_sqft - const__bldg_year_built - const__code_air - const__code_iso - const__code_rms - const__num_stories - country - county - geocode_match_level - item_key - latitude - limits__bi_limit - limits__bpp_limit - limits__building_limit - limits__signs_and_other_limit - limits__total_limit - longitude - occupancy__code_air - occupancy__code_atc - sovid - state - street - zip securitySchemes: tokenAuth: type: apiKey in: header name: Authorization description: Token-based authentication with required prefix "Token" cookieAuth: type: apiKey in: cookie name: sessionid ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.