ServingArea

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

Description

The Serving Area endpoint provides the API consumer with access to methods pertaining to serving areas and related data objects. The methods allow consumers to pull serving area data.

Methods

URL base/Workforce/ServingArea/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Serving Area.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
  {
    "HttpAction": "Get",
    "MethodName": "GetServingAreas",
    "Description": "Returns the list of all serving areas in the database.",
    "Path": "/Workforce/ServingArea/GetServingAreas"
  },
  {
    "HttpAction": "Get",
    "MethodName": "GetServingArea",
    "Description": "Returns the record for a single serving area given the passed in ID value (see Path)",
    "Path": "/Workforce/ServingArea/GetServingArea/25032"
  }
]
URL base/Workforce/ServingArea/GetServingAreas
Action GET
Description Returns a list of Serving Area objects in the M4 database.
Parameters None
Returns A list of JSON Serving Area data objects.
Sample Return Object 
[
  {
    "ID": 19,
    "SAName": "Hanover",
    "MapName": "",
    "ServingArea": "",
    "PremiseCount": null,
    "CustomerCount": null,
    "DSLAvailable": null,
    "DSLTake": null,
    "ISPTake": null,
    "TVAvailable": null,
    "TVTake": null,
    "WorkforceArea": null,
    "StructureLink": null
  },
  {
    "ID": 18,
    "SAName": "Henrico",
    "MapName": "",
    "ServingArea": "",
    "PremiseCount": null,
    "CustomerCount": null,
    "DSLAvailable": null,
    "DSLTake": null,
    "ISPTake": null,
    "TVAvailable": null,
    "TVTake": null,
    "WorkforceArea": null,
    "StructureLink": null
  }
]
URL base/Workforce/ServingArea/GetServingArea/ID
Action GET
Description Returns a Serving Area object when given an ID of a valid serving area in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a Serving Area in the M4 database.
Returns A JSON Service Status data object
Sample Return Object 
{
  "ID": 19,
  "SAName": "Hanover",
  "MapName": "",
  "ServingArea": "",
  "PremiseCount": null,
  "CustomerCount": null,
  "DSLAvailable": null,
  "DSLTake": null,
  "ISPTake": null,
  "TVAvailable": null,
  "TVTake": null,
  "WorkforceArea": null,
  "StructureLink": null
}
URL base/Workforce/ServingArea/GetServingAreasByAddress
Action POST
Description Returns a List of Serving Area objects when given the address of a building/structure.
Parameters
Name Required? Type Description
Address Yes String The address of the building/structure.
Sample JSON Package 
    {
        "Address": "601 Southlake Blvd, Richmond, VA 23236"
    }
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.

Address:
  • The address must be able to be geocoded by the geocoder used by the API.
Address:
  • The geocoded latitude/longitude values must be within the system configured projection.
Serving Areas:
  • The serving areas must exist as spatial representations in the database.
Address:
  • The address must be located within one or more serving areas.
URL base/Workforce/ServingArea/GetServingAreasByLatLong
Action POST
Description Returns a List of Serving Area objects when given the latitude/longitude of a building/structure.
Parameters
Name Required? Type Description
Latitude Yes Double The latitude of the building/structure
Longitude Yes Double The longitude of the building/structure
Sample JSON Package 
    {
        "Latitude": 37.500637,
        "Longitude": -77.596317
    }
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.

Latitude/Longitude:
  • The latitude/longitude must be valid.
Latitude/Longitude:
  • The latitude/longitude values must be within the system configured projection.
Serving Areas:
  • The serving areas must exist as spatial representations in the database.
Address:
  • The latitude/longitude must be located within one or more serving areas.

Was this article helpful?

Yes No

Related Articles