Structure

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Structure endpoint provides the API consumer with access to methods pertaining to structures and related data objects. The methods allow consumers to pull data and add, update, and delete structures.

Methods

URL base/MGeo/Structure/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Structure controller.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
  {
    "HttpAction": "Get",
    "MethodName": "GetStructure",
    "Description": "Gets the record for a single Structure given the passed in ID value (see Path).",
    "Path": "/Structure/GetStructure/25032"
  },
  {
    "HttpAction": "Post",
    "MethodName": "GetStructureByAddress",
    "Description": "Returns a record for a single Structure with a match to the address specified in the address parameter.",
    "Format": {
      "Address": "234 North Street, Washington, DC 20002"
    }
  }
]
URL base/MGeo/Structure/GetStructure/ID
Action GET
Description Returns a Structure object when given an ID of a valid structure in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a structure in the M4 database.
Returns A JSON Structure data object
Sample Return Object 
{
  "ID": 342720,
  "ParentID": 26,
  "FullAddress": "111 Sample Street Drive, Apt 12A, Sample City, VA 23236",
  "Description": "Description of this structure",
  "HouseNumber": "111",
  "PreDirectional": "PreDirectional Information",
  "Street": "Sample Street",
  "StreetSuffix": "Drive",
  "PostDirectional": "",
  "UnitNumber": "",
  "City": "",
  "State": "",
  "Zip_Code": "",
  "County": "",
  "Latitude": null,
  "Longitude": null,
  "CensusBlock": "060670011011085",
  "CensusTract": "06067001101",
  "Exchange": "",
  "StructureType": "Res",
  "Comments": "",
  "COID": null,
  "LoopLength": null,
  "Mapped": true,
  "LastUpdateUser": "Namey Namerson",
  "LastUpdateDate": "2015-01-30T11:40:48.037"
}
URL base/MGeo/Structure/GetStructureByAddress
Action POST
Description Returns a Structure object of a valid structure in the M4 database with a matching address.
Parameters
Name Required? Type Description
Address Yes String A JSON object that includes the full address of a structure
Sample JSON Package 
{
    "Address": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236"
}
Returns A JSON Structure data object
Sample Return Object 
{
  "ID": 257381,
  "ParentID": 25,
  "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
  "Description": "Description of this structure",
  "HouseNumber": "1234",
  "PreDirectional": "Up",
  "Street": "Palm Tree Drive",
  "StreetSuffix": "Apt 12A",
  "PostDirectional": "Down",
  "UnitNumber": "12A",
  "City": "Sample City",
  "State": "VA",
  "Zip_Code": "23236",
  "County": "Henrico",
  "Latitude": 1,
  "Longitude": 1,
  "CensusBlock": "060670011011085",
  "CensusTract": "06067001101",
  "Exchange": "Structure",
  "StructureType": "Res",
  "Comments": "This is a comment.",
  "COID": 24,
  "LoopLength": 500,
  "Mapped": true,
  "LastUpdateUser": "Namey Namerson",
  "LastUpdateDate": "2015-01-30T08:50:54.373"
}
Business Rules
  • There is a unique constraint on the “FullAddress” field in the database. At most, only 1 record can be returned for a given address.
  • Leading/trailing spaces are ignored in the address search parameter.
URL base/MGeo/Structure/GetStructuresByAddress
Action POST
Description Returns a collection of Structure objects in the M4 database that contains the address.
Parameters
Name Required? Type Description
Address Yes String A JSON object that includes the partial address of a structure to search for
Sample JSON Package 
{
    "Address": "Sample City, VA"
}
Returns A collection of JSON Structure data objects
Sample Return Object 
[
  {
    "ID": 257381,
    "ParentID": 25,
    "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
    "Description": "Description of this structure",
    "HouseNumber": "1234",
    "PreDirectional": "Up",
    "Street": "Palm Tree Drive",
    "StreetSuffix": "Apt 12A",
    "PostDirectional": "Down",
    "UnitNumber": "12A",
    "City": "Sample City",
    "State": "VA",
    "Zip_Code": "23236",
    "County": "Henrico",
    "Latitude": 1,
    "Longitude": 1,
    "CensusBlock": "060670011011085",
    "CensusTract": "06067001101",
    "Exchange": "Structure",
    "StructureType": "Res",
    "Comments": "This is a comment.",
    "COID": 24,
    "LoopLength": 500,
    "Mapped": true,
    "LastUpdateUser": "Namey Namerson",
    "LastUpdateDate": "2015-01-30T08:50:54.373"
  },
  {
    "ID": 257382,
    "ParentID": 25,
    "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
    "Description": "Description of this structure",
    "HouseNumber": "1234",
    "PreDirectional": "Up",
    "Street": "Palm Tree Drive",
    "StreetSuffix": "Apt 12A",
    "PostDirectional": "Down",
    "UnitNumber": "12A",
    "City": "Sample City",
    "State": "VA",
    "Zip_Code": "23236",
    "County": "Henrico",
    "Latitude": 1,
    "Longitude": 1,
    "CensusBlock": "060670011011085",
    "CensusTract": "06067001101",
    "Exchange": "Structure",
    "StructureType": "Res",
    "Comments": "This is a comment.",
    "COID": 24,
    "LoopLength": 500,
    "Mapped": true,
    "LastUpdateUser": "Namey Namerson",
    "LastUpdateDate": "2015-01-30T08:50:54.373"
  }
]
Business Rules
  • Address cannot be blank or null.
URL base/MGeo/Structure/GetStructuresByDescription
Action POST
Description Returns a list of structures that match the given description.
Parameters
Name Required? Code Description
Description Yes String A string representing a description of the structure.
Returns A list of JSON Structure data objects
Sample Return Object 
[
{
    "ID": 257381,
    "ParentID": 25,
    "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
    "Description": "Barn like structure",
    "HouseNumber": "1234",
    "PreDirectional": "Up",
    "Street": "Palm Tree Drive",
    "StreetSuffix": "Apt 12A",
    "PostDirectional": "Down",
    "UnitNumber": "12A",
    "City": "Sample City",
    "State": "VA",
    "Zip_Code": "23236",
    "County": "Henrico",
    "Latitude": 1,
    "Longitude": 1,
    "CensusBlock": "060670011011085",
    "CensusTract": "06067001101",
    "Exchange": "Structure",
    "StructureType": "Res",
    "Comments": "This is a comment.",
    "COID": 24,
    "LoopLength": 500,
    "Mapped": true,
    "LastUpdateUser": "Namey Namerson",
    "LastUpdateDate": "2015-01-30T08:50:54.373"
  },
  {
    "ID": 257396,
    "ParentID": null,
    "FullAddress": "2345 Palm Tree Drive, Sample City, VA 23236",
    "Description": "Barn like structure",
    "HouseNumber": "1234",
    "PreDirectional": "Up",
    "Street": "Palm Tree Drive",
    "StreetSuffix": "Apt 12A",
    "PostDirectional": "Down",
    "UnitNumber": "12A",
    "City": "Sample City",
    "State": "VA",
    "Zip_Code": "23236",
    "County": "Henrico",
    "Latitude": 1,
    "Longitude": 1,
    "CensusBlock": "060670011011085",
    "CensusTract": "06067001101",
    "Exchange": "Structure",
    "StructureType": "Res",
    "Comments": "This is a comment.",
    "COID": 24,
    "LoopLength": 500,
    "Mapped": true,
    "LastUpdateUser": "Namey Namerson",
    "LastUpdateDate": "2015-01-30T08:50:54.373"
}
]
URL base/MGeo/Structure/GetServingAreasByStructure/ID
Action GET
Description Returns a List of Serving Area objects when given the ID of a valid Structure in the M4 database.
Parameters
Name Required? Code Description
ID Yes Integer An integer value representing the ID of a Structure in the M4 database.
Returns A list of JSON Serving Area data objects
Sample Return Object 
[
{
    "ID": 3,
    "SAName": "Chesterfield County",
    "MapName": "",
    "ServingArea": "Chesterfield County",
    "PremiseCount": null,
    "CustomerCount": null,
    "DSLAvailable": null,
    "DSLTake": null,
    "ISPTake": null,
    "TVAvailable": null,
    "TVTake": null,
    "WorkforceArea": null,
    "StructureLink": null
},
{
    "ID": 4,
    "SAName": "Richmond County",
    "MapName": "",
    "ServingArea": "Richmond County",
    "PremiseCount": null,
    "CustomerCount": null,
    "DSLAvailable": null,
    "DSLTake": null,
    "ISPTake": null,
    "TVAvailable": null,
    "TVTake": null,
    "WorkforceArea": null,
    "StructureLink": null
}
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.

ID (structure ID):
  • The ID must be a valid structure in the database.
Serving Areas:
  • The serving areas must exist as spatial representations in the database.
ID (structure ID):
  • The structure must have valid spatial information that is located within one or more serving areas.
URL base/MGeo/Structure/AddStructure
Action POST
Description Returns the Structure object just added to the M4 database.
Parameters
Name Required? Type Description
ParentID No Integer The “ParentID” field allows API consumers to create a hierarchy with the ID field in the Structure table.
FullAddress No String The full address of the structure
Description No String The description of the structure
HouseNumber No String The street number of the structure
PreDirectional No String
Street No String The name of the street
StreetSuffix No String The suffix/type of street
PostDirectional No String
UnitNumber No String The unit number of the structure
City No String The city
State No String The state code
Zip_Code No String The zip code
County No String The county
Latitude No Double The latitude
Longitude No Double The longitude
CensusBlock No String Census Block as defined by the U.S. Census Bureau
CensusTract No String Census Tract as defined by the U.S. Census Bureau
Exchange No String
StructureType No String StructureType should either be "Res" or "Bus"
Comments No String
COID No Integer
LoopLength No Integer
Mapped No Boolean
LastUpdateUser No String
LastUpdateDate No DateTime
Sample JSON Package 
{
        "ParentID": 25,
        "FullAddress": "1234 Sample Street Drive, Apt 12A, Sample City, VA 23236",
        "Description": "Description of Structure",
        "HouseNumber": "1234",
        "PreDirectional": "PreDirectional Information",
        "Street": "Sample Street",
        "StreetSuffix": "Drive",
        "PostDirectional": "Position Directional Information",
        "UnitNumber": "Apt 12A",
        "City": "Sample City",
        "State": "VA",
        "Zip_Code": "23236",
        "County": "Richmond",
        "Latitude": 37.5407,
        "Longitude": 77.436,
        "CensusBlock": "060670011011085",
        "CensusTract": "06067001101",
        "Exchange": "",
        "StructureType": "Bus",
        "Comments": "Additional notes and comments",
        "COID": 24,
        "LoopLength": 17,
        "Mapped": true,
        "LastUpdateUser": "User Name",
        "LastUpdateDate": "2017-10-20T22:34:30.885-04:00"
    }
Returns A JSON Structure data object
Sample Return Object 
{
      "ID": 342927,
      "ParentID": 26,
      "FullAddress": "1234 Sample Street Drive, Apt 12A, Sample City, VA 23236",
      "Description": "Description of this structure",
      "HouseNumber": "1234",
      "PreDirectional": "PreDirectional Information",
      "Street": "Sample Street",
      "StreetSuffix": "Drive",
      "PostDirectional": "",
      "UnitNumber": "12A",
      "City": "",
      "State": "",
      "Zip_Code": "",
      "County": "",
      "Latitude": null,
      "Longitude": null,
      "CensusBlock": "060670011011085",
      "CensusTract": "06067001101",
      "Exchange": "",
      "StructureType": "Bus",
      "Comments": "",
      "COID": null,
      "LoopLength": null,
      "Mapped": true,
      "LastUpdateUser": "Namey Namerson",
      "LastUpdateDate": "2017-01-30T11:40:48.037"
    }
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • FullAddress: must be unique among all structures in the database.
  • LoopLength: must be greater than 0
  • Latitude: must be in the valid range defined for latitudinal values
  • Longitude: must be in the valid range defined for longitudinal values
  • Census Block: must be a valid Census Block as defined by the U.S. Census Bureau (15 digits or 16 digits with a period delimiter in tract)
  • Census Tract: must be a valid Census Tract as defined by the U.S. Census Bureau (11 digits or 12 digits with a period delimiter in tract)
  • StructureType: must be either "Res" or "Bus"
  • ParentID:
    • The “ParentID” field allows API consumers to create a hierarchy with the ID field in the Structure table.
    • Must be greater than 0.
    • Must exist as an existing structure in the database.
    • Cannot map to itself (i.e. a structure cannot be the parent of itself).
    • Cannot be mapped in such a way as to create a circular reference. (i.e. pointing a parent to a child structure).
URL base/MGeo/Structure/UpdateStructure
Action POST
Description Returns the Structure object just updated in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer The ID field of the Structure that needs to be updated in the Structure table.
ParentID No Integer The “ParentID” field allows API consumers to create a hierarchy with the ID field in the Structure table.
FullAddress No String The full address of the structure
Description No String The description of the structure
HouseNumber No String The street number of the structure
PreDirectional No String
Street No String The name of the street
StreetSuffix No String The suffix/type of street
PostDirectional No String
UnitNumber No String The unit number of the structure
City No String The city
State No String The state code
Zip_Code No String The zip code
County No String The county
Latitude No Double The latitude
Longitude No Double The longitude
CensusBlock No String Census Block as defined by the U.S. Census Bureau
CensusTract No String Census Tract as defined by the U.S. Census Bureau
Exchange No String
StructureType No String StructureType should either be "Res" or "Bus"
Comments No String
COID No Integer
LoopLength No Integer
Mapped No Boolean
LastUpdateUser No String
LastUpdateDate No DateTime
Sample JSON Package 
{
    "ID": 45,
    "ParentID": 25,
    "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
    "Description": "Description of Structure",
    "HouseNumber": "1234",
    "PreDirectional": "PreDirectional Information",
    "Street": "Palm Tree",
    "StreetSuffix": "Drive",
    "PostDirectional": "Position Directional Information",
    "UnitNumber": "Apt 12A",
    "City": "Sample City",
    "State": "VA",
    "Zip_Code": "23236",
    "County": "Richmond",
    "Latitude": 37.5407,
    "Longitude": 77.436,
    "CensusBlock": "060670011011085",
    "CensusTract": "06067001101",
    "Exchange": "",
    "StructureType": "Res",
    "Comments": "Additional notes and comments",
    "COID": 24,
    "LoopLength": 17,
    "Mapped": true,
    "LastUpdateUser": "User Name",
    "LastUpdateDate": "2017-10-20T22:39:31.873-04:00"
}
Returns A JSON Structure data object
Sample Return Object 
{
  "ID": 257381,
  "ParentID": 25,
  "FullAddress": "1234 Palm Tree Drive, Apt 12A, Sample City, VA 23236",
  "Description": "Description of this structure",
  "HouseNumber": "1234",
  "PreDirectional": "Up",
  "Street": "Palm Tree Drive",
  "StreetSuffix": "Apt 12A",
  "PostDirectional": "Down",
  "UnitNumber": "12A",
  "City": "Sample City",
  "State": "VA",
  "Zip_Code": "23236",
  "County": "Henrico",
  "Latitude": 1,
  "Longitude": 1,
  "CensusBlock": "060670011011085",
  "CensusTract": "06067001101",
  "Exchange": "Structure",
  "StructureType": "Res",
  "Comments": "This is a comment.",
  "COID": 24,
  "LoopLength": 500,
  "Mapped": true,
  "LastUpdateUser": "Namey Namerson",
  "LastUpdateDate": "2017-01-30T08:50:54.373"
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
    • ID: represents the ID of the structure to be updated.
    • Must be greater than 0.
  • FullAddress: must be unique among all structures in the database.
  • LoopLength: must be greater than 0
  • Latitude: must be in the valid range defined for latitudinal values
  • Longitude: must be in the valid range defined for longitudinal values
  • Census Block: must be a valid Census Block as defined by the U.S. Census Bureau (15 digits or 16 digits with a period delimiter in tract)
  • Census Tract: must be a valid Census Tract as defined by the U.S. Census Bureau (11 digits or 12 digits with a period delimiter in tract)
  • StructureType: must be either "Res" or "Bus"
  • ParentID:
    • The “ParentID” field allows API consumers to create a hierarchy with the ID field in the Structure table.
    • Must be greater than 0.
    • Must exist as an existing structure in the database.
    • Cannot map to itself (i.e. a structure cannot be the parent of itself).
    • Cannot be mapped in such a way as to create a circular reference. (i.e. pointing a parent to a child structure).
URL base/MGeo/Structure/RemoveStructure
Action POST
Description Deletes a Structure and all associated linkages.
Parameters
Name Required? Type Description
ID Yes Integer A JSON object that includes the ID of a valid structure
Sample JSON Package 
{
      "ID": 55
}
Returns A JSON object with a message either the confirming the deletion or notifying the user of an invalid ID.
Sample Return Object 
{
  "Message": "The Structure with ID [55] was deleted successfully."
}
Business Rules
  • ID: represents the ID of the structure to be deleted.
  • Must be greater than 0.

Was this article helpful?

Yes No

Related Articles