Export Formats

Supported file formats for bulk location exports.

JSON Format

The JSON export format provides a structured representation of location data with full nesting of related objects.

JSON Structure

{
  "exportTimestamp": "2025-06-08T15:30:00Z",
  "totalCount": 45678,
  "locations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:30:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "AUSTIN",
        "postalCode": "78701"
      },
      "address": {
        "streetNumber": "123",
        "streetName": "MAIN",
        "streetType": "STREET"
      },
      "fiberAccessDetails": {
        "circuitId": "CKT-78701-001",
        "fda": "FDA-001-TX-AUSTIN-78701",
        "dropStatus": "UNDERGROUND_COMPLETE",
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-06-01"
        }
      }
    }
  ]
}

JSON Export Fields

Field	Type	Description
exportTimestamp	ISO 8601 DateTime	When the export was generated (UTC with Z suffix)
totalCount	Number	Total number of locations in the export
locations	Array	Array of location objects

JSON Format Example

Complete location with all optional fields:

{
  "exportTimestamp": "2025-06-08T15:30:00Z",
  "totalCount": 2,
  "locations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:30:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "AUSTIN",
        "postalCode": "78701"
      },
      "address": {
        "streetNumber": "123",
        "streetName": "MAIN",
        "streetType": "ST",
        "subunitType": "APT",
        "subunitIdentifier": "100"
      },
      "coordinates": {
        "latitude": 30.2672,
        "longitude": -97.7431
      },
      "building": {
        "type": "MDU_COMPLEX",
        "identifier": "MAIN_PLAZA",
        "name": "Main Street Plaza",
        "totalUnits": 250
      },
      "fiberAccessDetails": {
        "circuitId": "CKT-78701-001",
        "fda": "FDA-001-TX-AUSTIN-78701",
        "dropStatus": "UNDERGROUND_COMPLETE",
        "serviceability": {
          "status": "ACTIVE",
          "availableDate": "2025-06-01"
        }
      },
      "locationGroupIds": [
        "456e7890-e89b-12d3-a456-426614174001"
      ],
      "addressGroupIds": [
        "789abcde-e89b-12d3-a456-426614174002"
      ]
    },
    {
      "id": "456e7890-e89b-12d3-a456-426614174001",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-06-01T14:30:00Z",
      "geography": {
        "country": "US",
        "region": "TX",
        "locality": "AUSTIN",
        "postalCode": "78702"
      },
      "coordinates": {
        "latitude": 30.2650,
        "longitude": -97.7400
      },
      "fiberAccessDetails": {
        "serviceability": {
          "status": "CONSTRUCTION",
          "availableDate": "2025-09-01"
        }
      }
    }
  ]
}

CSV Format

The CSV export format provides a flattened representation suitable for spreadsheet applications and data processing tools.

CSV Structure

id,createdAt,updatedAt,geography.country,geography.region,geography.locality,geography.postalCode,address.streetNumber,address.streetName,address.streetType,coordinates.latitude,coordinates.longitude,fiberAccessDetails.circuitId,fiberAccessDetails.serviceability.status,fiberAccessDetails.serviceability.availableDate
123e4567-e89b-12d3-a456-426614174000,2025-01-15T10:00:00Z,2025-06-01T14:30:00Z,US,TX,AUSTIN,78701,123,MAIN,STREET,30.2672,-97.7431,CKT-78701-001,ACTIVE,2025-06-01
456e7890-e89b-12d3-a456-426614174001,2025-01-15T10:00:00Z,2025-06-01T14:30:00Z,US,TX,AUSTIN,78702,,,,30.2650,-97.7400,,CONSTRUCTION,2025-09-01

CSV Export Notes

• Encoding: UTF-8
• Header Row: Always included
• Delimiter: Comma (,)
• Quote Character: Double quote (") for fields containing commas or newlines
• Nested Objects: Use dot notation (e.g., geography.country)
• Arrays: Pipe-separated values within the field (e.g., FIBER|COPPER)
• Empty Values: Represented as empty strings
• Timestamps: ISO 8601 format with UTC (Z suffix for DateTimes)

CSV Column Mapping

CSV Column	JSON Path	Type	Notes
id	id	UUID	Location identifier
createdAt	createdAt	DateTime	UTC with Z suffix
updatedAt	updatedAt	DateTime	UTC with Z suffix
geography.country	geography.country	String	ISO country code
geography.region	geography.region	String	State/province code
geography.locality	geography.locality	String	City name
geography.postalCode	geography.postalCode	String	Postal/ZIP code
address.streetNumber	address.streetNumber	String	Optional
address.streetName	address.streetName	String	Optional
address.streetType	address.streetType	String	Optional
address.streetSuffix	address.streetSuffix	String	Optional
address.subunitType	address.subunitType	String	Optional
address.subunitIdentifier	address.subunitIdentifier	String	Optional
coordinates.latitude	coordinates.latitude	Number	Optional
coordinates.longitude	coordinates.longitude	Number	Optional
building.type	building.type	String	Optional
building.identifier	building.identifier	String	Optional
building.name	building.name	String	Optional
building.totalUnits	building.totalUnits	Number	Optional
fiberAccessDetails.circuitId	fiberAccessDetails.circuitId	String	Optional
fiberAccessDetails.fda	fiberAccessDetails.fda	String	Optional
fiberAccessDetails.fdh	fiberAccessDetails.fdh	String	Optional
fiberAccessDetails.splitterPort	fiberAccessDetails.splitterPort	String	Optional
fiberAccessDetails.layer2AccessProtocol	fiberAccessDetails.layer2AccessProtocol	String	Optional
fiberAccessDetails.dropStatus	fiberAccessDetails.dropStatus	String	Optional
fiberAccessDetails.serviceability.status	fiberAccessDetails.serviceability.status	String	Optional
fiberAccessDetails.serviceability.availableDate	fiberAccessDetails.serviceability.availableDate	Date	Optional
locationGroupIds	locationGroupIds	Array	Pipe-separated UUIDs
addressGroupIds	addressGroupIds	Array	Pipe-separated UUIDs

CSV Format Example

Complete export with multiple locations:

id,createdAt,updatedAt,geography.country,geography.region,geography.locality,geography.postalCode,address.streetNumber,address.streetName,address.streetType,address.streetSuffix,address.subunitType,address.subunitIdentifier,coordinates.latitude,coordinates.longitude,building.type,building.identifier,building.name,building.totalUnits,fiberAccessDetails.circuitId,fiberAccessDetails.fda,fiberAccessDetails.fdh,fiberAccessDetails.splitterPort,fiberAccessDetails.layer2AccessProtocol,fiberAccessDetails.dropStatus,fiberAccessDetails.serviceability.status,fiberAccessDetails.serviceability.availableDate,locationGroupIds,addressGroupIds
123e4567-e89b-12d3-a456-426614174000,2025-01-15T10:00:00Z,2025-06-01T14:30:00Z,US,TX,AUSTIN,78701,123,MAIN,ST,,APT,100,30.2672,-97.7431,MDU_COMPLEX,MAIN_PLAZA,Main Street Plaza,250,CKT-78701-001,FDA-001-TX-AUSTIN-78701,FDH-MAIN-ST-001,PORT-16-04,GPON,UNDERGROUND_COMPLETE,ACTIVE,2025-06-01,456e7890-e89b-12d3-a456-426614174001,789abcde-e89b-12d3-a456-426614174002
456e7890-e89b-12d3-a456-426614174001,2025-01-15T10:00:00Z,2025-06-01T14:30:00Z,US,TX,AUSTIN,78702,,,,,,,,30.2650,-97.7400,,,,,,,,,,,CONSTRUCTION,2025-09-01,,
789abcde-e89b-12d3-a456-426614174002,2025-01-15T10:00:00Z,2025-06-01T14:30:00Z,US,CA,SAN FRANCISCO,94105,456,MARKET,ST,,STE,200,37.7897,-122.3972,,,,,,,,,,,ACTIVE,2025-03-01,,

Format Selection Guidelines

Choose JSON when:

• You need to preserve the full structure of nested objects
• Your processing system can handle JSON parsing
• You want to minimize data duplication
• You need to maintain data type precision

Choose CSV when:

• You need to import data into spreadsheet applications
• Your processing system prefers tabular data
• You want maximum compatibility with data analysis tools
• You need simple row-based processing