Location Services API Programming Reference Guide
First Published: February 27, 2013
Last Modified: March 05, 2014
Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
Text Part Number: PN OL-30024-03
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.
THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.
The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version
of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.
NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED "AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.
IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: http://
www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership
relationship between Cisco and any other company. (1110R)
Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown
for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.
Adobe Systems, Inc.
Adobe LiveCycle Data Services ES2.5, Copyright © 2010, Adobe Systems, Inc. All Rights Reserved
Oracle
Copyright ©2012, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
Red Hat, Inc.
Red Hat and Red Hat Enterprise Linux are trademarks of Red Hat, Inc., registered in the United States and other countries.
Other product names, symbols, and phrases used throughout this document (if any) are property of their respective owners.
Videoscape Location Services Users Guide
© Cisco Systems, Inc. All rights reserved.
CONTENTS
Preface
Preface v
Audience v
About This Guide v
Document Organization v
Document Conventions vi
Definitions and Acronyms vii
Document Definitions vii
Document Acronyms viii
CHAPTER 1
Videoscape Location Services Application Overview 1
Videoscape Location Services Overview 1
Location Service API Overview 2
CHAPTER 2
Application Programming Interface for the Videoscape Location Service 5
Core Data Services 5
Service Provider Subnet Data 5
Service Provider Subnet Data File 6
Service Provider Location Data File 6
Custom Zone Definitions 7
Assigning a Namespace to a Zone Group 8
Assigning Classifiers to a Zone Group 8
Creating Zones for a Zone Group 9
TARGET Location Zone Matching 10
Zone Import File Format 10
Neustar Geolocation Data 13
Location Services Application Regions 16
Core Location Service Interface 16
Location Services API Programming Reference Guide
PN OL-30024-03
iii
Contents
Get Location - HTTP GET 16
Zone Definition Interface 19
Get Provider Name List 19
Get Zone 20
Get Zone Group 21
Get Zone Group List 22
Create Classifiers 23
Emergency Alert System 24
FIPS State and Territory Code 24
Standard Geographical Classification Codes 26
EAS Location Service Interfaces 28
Get EAS Location - HTTP GET 28
Get EAS Alert Target 32
Get EAS Alert Target Map 35
Set EAS Alert Targets 37
Get Controller List 38
Delete Controller 39
Set EAS Alert Target Map 40
Geographic Region Interface 41
GET Region Data 41
APPENDIX A
Zone Import File Format Example 47
Zone Import File Format Example 47
Location Services API Programming Reference Guide
iv
PN OL-30024-03
Preface
• Audience, page v
• Document Organization, page v
• Document Conventions, page vi
• Definitions and Acronyms, page vii
Audience
This guide is intended to be used by System Administrators and Service Providers.
About This Guide
This guide contains instructions for the installation and configuration of the Videoscape Location Service
application software.
Document Organization
This document is organized into the following chapters:
Chapter/Appendix
Description
Chapter 1 - Videoscape Location
Services Application Overview
Provides a product overview for Videoscape Location Services
application.
Chapter 2 - Application Programming Provides all API information, as it pertains to the Videoscape Location
Interface for the Videoscape Location Services application.
Service Application
Appendix A - Zone Import File
Format Example
Provides an example of the format used in the Zone Import File.
Location Services API Programming Reference Guide
PN OL-30024-03
v
Preface
Document Conventions
Document Conventions
This document uses the following conventions:
Convention
Description
^ or Ctrl
Both the ^ symbol and Ctrl represent the Control (Ctrl) key on a keyboard.
For example, the key combination ^D or Ctrl-D means that you hold
down the Control key while you press the D key. (Keys are indicated in
capital letters but are not case sensitive.)
bold font
Commands and keywords and user-entered text appear in bold font.
Italic font
Document titles, new or emphasized terms, and arguments for which you
supply values are in italic font.
Courier font
Terminal sessions and information the system displays appear in courier
font.
Bold Courier font
Bold Courier font indicates text that the user must enter.
[x]
Elements in square brackets are optional.
...
An ellipsis (three consecutive nonbolded periods without spaces) after
a syntax element indicates that the element can be repeated.
|
A vertical line, called a pipe, indicates a choice within a set of keywords
or arguments.
[x | y]
Optional alternative keywords are grouped in brackets and separated by
vertical bars.
{x | y}
Required alternative keywords are grouped in braces and separated by
vertical bars.
[x {y | z}]
Nested set of square brackets or braces indicate optional or required
choices within optional or required elements. Braces and a vertical bar
within square brackets indicate a required choice within an optional
element.
string
A nonquoted set of characters. Do not use quotation marks around the
string or the string will include the quotation marks.
<>
Nonprinting characters such as passwords are in angle brackets.
[]
Default responses to system prompts are in square brackets.
!, #
An exclamation point (!) or a pound sign (#) at the beginning of a line
of code indicates a comment line.
Location Services API Programming Reference Guide
vi
PN OL-30024-03
Preface
Definitions and Acronyms
Reader Alert Conventions
This document uses the following conventions for reader alerts:
Note
Tip
Caution
Timesaver
Warning
Means reader take note. Notes contain helpful suggestions or references to material not covered in the
manual.
Means the following information will help you solve a problem.
Means reader be careful. In this situation, you might do something that could result in equipment damage
or loss of data.
Means the described action saves time. You can save time by performing the action described in the
paragraph.
Means reader be warned. In this situation, you might perform an action that could result in bodily
injury.
Definitions and Acronyms
This section provides the definitions and acronyms that are used throughout this guide.
Document Definitions
Definition Description
Civic
Location
Country, Province, City, and so on.
Geodetic
Location
Latitude and Longitude
LS Client
Location Service Client - Any Videoscape component or service that invokes the Location
Service.
Location Services API Programming Reference Guide
PN OL-30024-03
vii
Preface
Document Acronyms
Document Acronyms
Definition Description
ASN
Autonomous System Numbers
BSG
Broadcast Service Group
CPE
Consumer Premise Equipment
CIDR
Classless Inter-Domain Routing
CMTS
Cable Modem Termination System
CSV
Comma Separated Value (File)
DTA
Digital Transport Adapter
EAS
Emergency Alert System
EC
Explorer Controller
ECS
Explorer Control System
FIPS
Federal Information Processing Standards (US)
LS
Location Service
OOBB
Out of Band Bridge
QPSK
Quadrature Phase-Shift Keying
SGC
Standard Geographical Classification (Canada)
SP
Service Provider
Location Services API Programming Reference Guide
viii
PN OL-30024-03
CHAPTER
1
Videoscape Location Services Application
Overview
• Videoscape Location Services Overview, page 1
• Location Service API Overview, page 2
Videoscape Location Services Overview
The Location Service is a horizontally scalable and redundant service capable of providing geodetic, civic,
and network access data based on IP subnet data queried and loaded into its databases. It should be noted that
the network access data specifically identifies edge network elements of the access network infrastructure.
Such elements have geodetic and/or civic and/or network access metadata associated.
The Location Service also supports other types of location information. This information includes Emergency
Alert System (EAS) information and application specific Zone definitions.
The following figure illustrates the detailed architecture of the Cisco Location Service.
Location Services API Programming Reference Guide
PN OL-30024-03
1
Videoscape Location Services Application Overview
Location Service API Overview
The Location Service Engine is responsible for handling location service requests from Client applications
(identified as Location Service Client). The request from the Location Service Client routes through a load
balancer to an available Location Service VM instance.
The Location Service obtains its data through either static configuration or push/pull based interfaces to 3rd
party data sources. Static data sources include the MaxMind geolocation data, network subnet data, EAS data,
and application specific Zone data. Pull-based interface data sources include Neustar (fka Quova) geolocation
data. The Location Service supports push-based data for the EAS data associated with Explorer Controllers
(EC) and DTA Control Suite (DTACS). The Location Service stores push-based data inside a data grid so
that the data is available to all LS instances.
In order to maximize performance, the Location Service caches the location data in a memory based cache
called the Location Data Cache. The Location Service Engine never queries static data directly in order to
fulfill a location request. Instead, it always uses the data cached in memory for performance and scalability
purposes. For pull based interfaces, if the data is not currently in the Location Data Cache, the Location Service
Engine uses the interface to pull the location data from the data source. For data stored in the data grid, the
Location Service leverages the caching capabilities of the data grid to achieve performance.
Unlike the MaxMind geolocation data set, Neustar provides its data as an external service. Neustar provides
both a Java Client and web service interface. The Location Service currently uses the Java Client to call the
Neustar service to obtain the geolocation data.
Location Service API Overview
The Location Service API is a pull based API, where the Location Service Client queries the Location Service
each time it needs to retrieve the Target location. This data may be cached by the LS Client if specified in the
Location Service response. Although multiple sources of location data may exist (that is, both Neustar and
MaxMind provide 3rd party geolocation data), typically only one 3rd party geolocation data source is available
to the Location Service in a given deployment.
The Location Service Client request must specify the Target IP address in its location query. The Location
Service Engine determines the geodetic, civic, and network access data based on the supplied Target IP address.
The Location Service searches all data sources in the order specified below. Note that once a match is found,
the Location Service terminates its search and returns the matching data. The exception is the Service Provider
subnet data, as specified below:
1 Search Location Data Cache for a match against the Service Provider subnet data. If location data is not
included with the Service Provider subnet data, the Location Service continues searching 3rd party
geolocation sources for location data, but uses Network data from Service Provider subnet data
2 Search the Location Data Cache for a match against the MaxMind subnet data or call the external Neustar
service to obtain geolocation data, depending on the data source configuration.
3
An operator may specify application specific zone information. The zone data provides a method to aggregate
locations into logical regions that are application to a specific application. For example, one application may
be advertising. Another might be peering networks. The Location Service can return the matching zones when
performing a location lookup so that the data is available to the LS Client.
The Location Service supports Emergency Alert System (EAS) data. EAS support comes in two flavors: static
data mapping geolocation to EAS code or operator configured data mapping EC downstream plant or DTACS
multicast information to EAS codes. For the static geolocation mapping, the LS Client specifies a geolocation
and the LS returns a set of EAS codes associated with that region. For the EC/DTACS EAS data, the LS Client
Location Services API Programming Reference Guide
2
PN OL-30024-03
Videoscape Location Services Application Overview
Location Service API Overview
specifies an EAS code and the LS returns the EC downstream plants and DTACS multicasts associated with
the EAS code.
Location Services API Programming Reference Guide
PN OL-30024-03
3
Videoscape Location Services Application Overview
Location Service API Overview
Location Services API Programming Reference Guide
4
PN OL-30024-03
CHAPTER
2
Application Programming Interface for the
Videoscape Location Service
• Core Data Services, page 5
• Location Services Application Regions, page 16
Core Data Services
The Core Data Services include the following:
• Service Provide Subnet Data
• MaxMind Data
• Geolocation Data
Service Provider Subnet Data
The Service Provider (SP) may manage one or more networks that provide "last mile" delivery to the subscriber.
When a subscriber uses one of these networks to access content, access is described as "on the SP network"
or "on net".
The Videoscape Location Service provides a method to load SP Subnet Data, which specifies the mapping
of a set of subnets to each network type managed by the SP. By looking up a TARGET IP address, the LS
determines which SP network the subscriber is accessing, if any. For example, an SP may provide
Cable/DOCSIS access and LTE access. The SP supplies the subnets that are managed on each network. When
a CPE accesses content, the LS uses the IP address of the CPE to determine if it matches one of the supplied
IP addresses. If so, it returns the network identifier. Otherwise, it indicates that the CPE is off net.
In addition to identifying the network associated with the subnet data, the SP may also supply civic and
geodetic information. Typically, the SP has more accurate location information than the 3rd party geolocation
databases. By providing this information to the Location Service, the SP is able to accurately indicate the
location of the TARGET. For example, an SP knows which subnets are assigned to each CMTS. The SP also
knows the regions serviced by each CMTS. The SP obtains the civic location data (e.g. city, state, country)
and an approximate geodetic location of the region serviced by each CMTS. The SP encodes this location in
Location Services API Programming Reference Guide
PN OL-30024-03
5
Application Programming Interface for the Videoscape Location Service
Service Provider Subnet Data
the data loaded into the SP Subnet Data. Given an IP address, the LS can determine the association of subnet
to CMTS and thus to service region.
The LS uses two data sources (SP Subnet and SP Location) to define the SP Subnet Data and the associated
Location. These data sources are formatted as comma separated value (CSV) files.
Service Provider Subnet Data File
The SP Subnet Data File specifies the list of subnets assigned to each SP network. At a minimum, the subnet
and "on net" name must be supplied. Each unique network managed by the SP must be identified by a unique
name. This name is returned by the Videoscape Location Service, as the "on net" identifier. Optionally, the
Location Name and ASN may be supplied.
The following is an example of the CSV file field structure:
Subnet,Location_Name,OnNetName,ASN
The following table describes the fields contained in the previous structure.
Field
Type
Required
Description
SubNet
String
R
Subnet of the device using Classless Inter-Domain Routing (CIDR)
notation. For example:
198.51.100.0/22
LocationName String
R
Name of the location of the subnet. This references an entry in the SP
Location Data File. Note that although a value must be provided, if the
SP does not supply the SP Location Data File, this field is ignored.
OnNetName String
R
Name of the "on net" network. For example, one service provider may
specify "MOBILE" and "DOCSIS", another may only have a single
"on net" network and may specify "FIXED". The naming convention
used is created by the SP.
ASN
O
The Autonomous System Number (ASN) identifies the network
operator, such as an ISP.
Integer
* R - required field, O - optional field
Subnet Data Examples:
198.51.100.0/22,PA_Lansdale,DOCSIS,6161
192.51.108.0/22,PA_NorthWales,DOCSIS,6161
192.51.112.0/22,PA_Hatfield,DOCSIS,6161
Service Provider Location Data File
The SP Location Data File is an optional file that maps the locations specified in the SP Subnet Data File to
civic and geodetic locations. The civic locations specify named regions, such as city, state, metro code, and
country. The geodetic location data is the latitude and longitude of the centroid of the civic region.
The following is an example of the CSV file field structure:
LocationName,Latitude,Longitude,City,State/Province,MetroCode,CountryCode,Timezone
The following table describes the fields contained in the previous structure.
Location Services API Programming Reference Guide
6
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
Field
Type
Required
Description
LocationName String
R
Unique name of the location. Zero of more subnet entries may reference
this location name.
Latitude
Float
R
Latitude, in degrees of the centroid of the service region.
Longitude
Float
R
Longitude, in degrees of the centroid of the service region.
City
String
R
Name of the city associated with the location.
State/Province String
R
State or province in which the city is located.
MetroCode
O
Metro code assigned to the service region.
CountryCode String
R
Two character country code based on ISO 3166.
Timezone
O
Time zone information (for example, EST, PDT, -4, -8, and so on)
Integer
String
* R - required field, O - optional field
Location Data Examples:
PA_Lansdale,40.2414,-75.2842,Lansdale,PA,504,US,EST
PA_NorthWales,40.2108,-75.2786,North Wales,PA,504,US,EST
PA_Hatfield,40.2797,-75.2997,Hatfield,PA,504,US,EST
From the previous examples, a request from CPE 192.51.108.34 refers to the location PA_NorthWales. The
LS would return civic and geodetic data associated with this location from the above example.
Custom Zone Definitions
The Location Service allows a Service or Content Provider to define their own application specific zones.
These zones may have different purposes, such as advertising, blackouts, and so on. The logical grouping of
a set of zones for a specific application, for a specific provider, is called a Zone Group. Each provider may
define zero or more zone groups. Each zone group has a unique name for that provider. The combination of
Provider and Zone Group names creates a globally unique namespace for the Zone Group.
Each zone group is composed of a set of zones. A zone is a region, within which all CPEs or subscribers have
a common set of application specific attributes. A zone can be constructed by a list of geolocations and different
types of geolocation data can be used to define a single zone.
The following is an example set of Providers, each with a multiple Zone Group definitions.
• Provider 1
◦Zone Group - Geographic Ad Zone
◦Zone 1 - PA + NJ + DE
◦Zone 2 - NY + CT
◦Zone 3 - and so on.
◦Zone Group - Political Party
◦Zone 1 - zip codes whose population are 60%+ Democrat
Location Services API Programming Reference Guide
PN OL-30024-03
7
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
◦Zone 2 - zip codes whose population are 60%+ Republican
◦Zone 3 - remaining zip codes
◦Zone Group - Philly Northern Suburbs Ad Zone
◦Zone 1 - city of Perkasie, city of Quakertown, zip codes for Milford Township
◦Zone 2 - city of Lansdale, zip codes for Montgomeryville
◦Zone 3 - and so on.
• Provider 2
◦Zone Group - ASN Peering Groups
◦Zone 1 - List of ASNs for Verizon
◦Zone 2 - List of ASNs for AT&T
◦Zone 3 - and so on.
◦Zone Group - DMAs
◦Zone 1 - Philly DMA
◦Zone 2 - Boston DMA
◦Zone 3 - and so on.
When performing a geolocation lookup, the LS Client may choose to obtain zone information for a specific
zone group or for all zone groups. When the LS receives the geolocation request, it locates all zones in the
selected Zone Group (or all Zone Groups) which match the TARGET location. The LS Client can use the
returned zone information to apply policy.
Assigning a Namespace to a Zone Group
A provider may have multiple applications or profiles that it wants to apply, and thus may define multiple
Zone Groups. The provider must assign a unique name to each Zone Group. Note that the name only needs
to be unique for that provider. The combination of unique provider name and unique Zone Group name (within
a provider) define a unique namespace for a Zone Group.
A namespace is created by concatenating the provider name, a period, and the Zone Group name:
provider_name.zone_group_name
For example:
cisco.ad_campaign_3
Note that since a period is used to define the namespace, a period is an invalid character for the provider name
and Zone Group name.
Assigning Classifiers to a Zone Group
A Classifier is an identifier used to associate an application specific zone lookup with a specific zone group.
For example, the LS Client may not have access to the namespace but instead has access to some type of
Location Services API Programming Reference Guide
8
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
identifier associated with the zone group. Each zone group may be assigned a set of Classifiers. A Classifier
can be specified by the LS Client, allowing the Videoscape LS to find the zone group associated with that
Classifier, and thus find the appropriate zone group to search for matching zones.
For example, a Service Provider has a white label CDN, and content providers use that CDN to deliver their
content. A Service Broker, which has CDN selection rules, receives a content request from a CPE for a
particular content URL. The CDN Selection rules may reference zone groups defined for their respective
content providers. However, the Service Broker has no method to associate a content URL with a Zone Group
Namespace, and thus, cannot specify the namespace to the LS. Instead, when defining the zone groups, the
domain of the content URL is used as a Classifier. Once specified, the Service Broker passes in the domain
of the URL it receives, which the LS uses to identify the zone group in order for it to return the correct zone
information to the Service Broker.
A classifier may be a simple string or it may be a regex expression. Simple strings must match (case insensitive)
the classifier string specified in the geolocation query.
Since the classifier is meant to identify a Zone Group across multiple providers, the classifier value must be
a unique string across all Zone Group definitions. Duplicate Classifier values will be rejected. Thus, the
Location Service accepts the first instance of that Classifier that it finds and ignores the duplicate values on
subsequent Zone Group definitions. Note that it is possible to create different regex expressions that generate
the same results. The Location Service cannot statically detect this condition. Therefore, the first matching
Zone Group is used at run time
Creating Zones for a Zone Group
Each Zone Group is composed of one or more geographic regions called Zones. These zones have relevance
only to the zone group in which they reside. Thus, the zones defined for one zone group do not impact any
other zone group. The zones within a zone group are each assigned a name that is unique within that zone
group. Note that a zone name may be duplicated in different zone groups.
A Zone is defined by a set of one or more location elements. The location could be a DMA, zip code, country
code, and so on. Different location types may be specified for a given zone. Thus, a zone may be defined by
a particular DMA plus five different zip-codes. The following is a list of location types that can be used to
define a zone:
• OnNetName
• CountryCode
• State
• City
• MetroCode
• ASN
• PostalCode
• Subnet
With a couple of exceptions, these names correspond to the Videoscape LS "Get Location" API response.
The PostalCode represents the Postal Code or Zip Code of a TARGET IP address. The subnet can be any
subnet value defined using the Classless Inter-Domain Routing (CIDR) notation.
Note that even though the zone definition is flexible, the geolocation data available to the LS may only have
a subset of the above location types available. For example, if using 3rd party geolocation source, if the Service
Location Services API Programming Reference Guide
PN OL-30024-03
9
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
Provider does not choose the data source option that includes a postal code, then any zone defined using postal
codes would never match a TARGET location.
The LS does not enforce any constraints on the region definition of a Zone. Thus, zones may overlap even
within a zone group. Zones may also be disjoint, specifying only a subset of the coverage area.
TARGET Location Zone Matching
When a Location Service Client queries the Location Service for the TARGET location, the client can request
matching Zone information in the response. The LS Client must specify either the zone namespace, zone
classifier value, or request all zone groups.
The Location Service determines the candidate Zone Groups to search, based on the LS Client request. If the
request specified a zone namespace, the candidate Zone Group list contains either the Zone Group matching
the namespace or no Zone Groups (in case there is no namespace match). If the request specified a Classifier,
the Location Service compares the specified Classifier with all Zone Group Classifiers (either a case insensitive
compare or regex compare). The first matching Zone Group is added to the candidate list. If the request
specifies all zone groups, then all zone groups are added to the candidate list.
The Location Service determines the location of the TARGET based on the TARGET IP address. Thie location
includes geolocation, civic, and network location. The Location Service then searches through the Zone
definitions from Zone Groups in the candidate list to find all Zones that match the TARGET location. If the
TARGET location matches ANY of the location parameters defined for a Zone, that Zone is considered a
match.
When a LS Client queries the LS for the TARGET location, the LS optionally returns the matching zone
information. The LS determines the location of the TARGET based on the TARGET IP address, and then
searches the zone definitions to find all zones that match the TARGET location. If the TARGET location
matches any of the location parameters defined for a zone, that zone is considered a match. Thus, the zone
definition is treated as a union of the locations that comprise that zone. If the TARGET location intersects
that zone at any point, the TARGET is considered within that zone and thus the zone is a match. Thus, the
Zone definition is treated as a union of the locations that comprise that Zone. If the TARGET location intersects
that Zone at any point, the TARGET is considered within that Zone and thus the Zone is a match
For example, if a Zone X is defined as DMA 200 and State NY, if the TARGET is either in DMA 200 or is
located in the state of NY, then the TARGET is considered within Zone X.
The Location Service returns all Zone definitions that match the TARGET location from the Zone Groups in
the candidate list. Thus, zero or more Zones is returned in the LS response.
Zone Import File Format
Listed below is the import file format to support providers, Zone Groups, and Zones. The service provider
may use a file or the Zone API to define zones. When using a file import, the file must contain all provider,
zone group and zone definitions. The Location Service does not support incremental updates when using an
import.
Element: ZoneDefinitions
Children: ProviderNameList (0..N)
ZoneGroupList (0..N)
Element: ProviderNameList
Children: ProviderName (0..N)
Location Services API Programming Reference Guide
10
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
Element: ProviderName
Children: None
Type
R/O
Description
String
R
The unique name of the provider.
Element: ZoneGroupList
Children: ZoneGroup (0..N)
Element: ZoneGroup
Children: Classifier (0..N)
Zone (0..N)
Attribute Type
R/O
Description
Name
String
R
The unique name of the Zone Group.
Provider
String
R
The Provider that defined the Zone Group.
The Classifier includes a type attribute to identify whether it is a simple string compare or a regex expression.
It also includes a data portion with the actual classifier data.
Element: Classifier
Children: None
Attribute Type
R/O
Description
Name
String
R
Indicates whether the Classifier is a simple string or a regex expression.
Valid values include:
simple | regex
String
R
Classifier data, which is either a string to match or a regex expression.
Element: Zone
Children: OnNetName (0..N), CountryCode (0..N), State (0..N), City (0..N), MetroCode (0..N), ASN
(0..N), PostalCode (0..N), Subnet (0..N)
Attribute Type
R/O
Description
Name
R
A unique Zone Name within this Zone Group.
String
Element: OnNetName
Children: None
Type
R/O
Description
Location Services API Programming Reference Guide
PN OL-30024-03
11
Application Programming Interface for the Videoscape Location Service
Custom Zone Definitions
String
R
This is the "on net" network name, which is specified in the SP Subnet File.
The LS source data must include SP Subnet File data in order to use this
location type in the Zone definition.
Element: Country Code
Children: None
Type
R/O
Description
String
R
The two character, country code based on ISO 3166. The LS source must
include either 3rd party geolocation data (for example, MaxMind, Quova) or
location data in the SP Subnet File.
Element: State
Children: None
Type
R/O
Description
String
R
The abbreviation for the state or province. The LS source must include either
3rd party geolocation data (for example, MaxMind, Quova) or location data in
the SP Subnet File.
Element: City
Children: None
Type
R/O
Description
String
R
The name of the city. The LS source must include either 3rd party geolocation
data (for example, MaxMind, Quova) or location data in the SP Subnet File.
Element: MetroCode
Children: None
Type
R/O
Description
String
R
The metro code assigned to the city. The LS source must include either 3rd
party geolocation data (for example, MaxMind, Quova) or location data in the
SP Subnet File.
Element: ASN
Children: None
Type
R/O
Description
Location Services API Programming Reference Guide
12
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Neustar Geolocation Data
String
R
The Autonomous System Number (ASN) that identifies the network operator,
such as an ISP. The LS source must include either 3rd party geolocation data
(for example, MaxMind, Quova) or location data in the SP Subnet File.
Element: PostalCode
Children: None
Type
R/O
Description
String
R
The zip-code or postal code. The LS source must include either 3rd party
geolocation data (for example, MaxMind, Quova).
Element: Subnet
Children: None
Type
R/O
Description
String
R
The subnet of the device using Classless Inter-Domain Routing (CIDR)
notation. For example:
198.51.100.0/22
Refer to Zone Import File Format Example, on page 47 for a sample import file.
Neustar Geolocation Data
For detailed Neustar specifications, refer to the following Neustar web site:
http://extranet.quova.com
Neustar provides access to the geolocation data through an API on the Neustar GeoDirectory Server. The
GeoDirectory Server runs on the following platforms:
• Microsoft Windows Server 2003
• Microsoft XP Professional, Server 2008
• Red Hat Enterprise Linux 3, 4 or 5 (including AMD 64-bit)
• Sun Solaris 8, 9 or 10 Operating Environment (SPARC processors only)
The LS communicates with the GeoDirectory Server over TCP, using a Java API.
The following table describes the data provided by the geolocation API.
Location Services API Programming Reference Guide
PN OL-30024-03
13
Application Programming Interface for the Videoscape Location Service
Neustar Geolocation Data
Field
Example
Continent North
America
Description
Neustar supports the following continents:
• Africa
• Antarctica
• Asia
• Australia
• Europe
• North America
• South America
Country
US
Neustar supplies the country of origin for the IP address connection, identified
using the International Standard Organization (ISO) two letter country codes
defined in ISO-3166.
Country
CF
99
The Country Confidence Factor (CF) is a number from 0-99 that provides an
indication of the likelihood that the user is in the same country that is assigned to
the IP address. The higher the number, the more the evidence points to the user
being in the same location as the IP address.
Region
Mid Atlantic The region includes generic regional information (for example, Northwest) and
some country-specific regions (for example, Northern Ireland). Region information
is currently available for the following:
• US
• UK
• Brazil
• Denmark
• France
• Philippines
State
PA
Neustar provides information for States and Provinces (that is, the first level
administration division) in all countries where they exist.
State CF
99
The State Confidence Factor (CF) is a number from 0-99 that provides an indication
of the likelihood that the user is in the same state that is assigned to the IP address.
The higher the number, the more likely the user being in the same location as the
IP address.
City
Philadelphia Neustar locates users to their individual cites and recognizes over 95,000 distinct
international locations.
City CF
80
The City Confidence Factor (CF) is a number from 0-99 that provides an indication
of the likelihood that the user is in the same city that is assigned to the IP address.
The higher the number, the more the evidence points to the user being in the same
location as the IP address.
Location Services API Programming Reference Guide
14
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Neustar Geolocation Data
Field
Example
Description
DMA
504
Designated Market Areas (DMAs) are groupings of United States counties that
are reached by a specific groups of television stations, as specified by Nielsen
Media Research. DMAs are often used by advertisers to segregate and target
specific areas of the country. There are 210 DMAs in the United States.
MSA
37980
Metropolitan and Micropolitan Statistical Areas (MSAs) are geographical
boundaries of United States counties or towns, as defined by the United States
Office of Management and Budget (OMB) from data gathered by the United States
Census Bureau. The OMB defines the combination of Metropolitan and
Micropolitan Statistical areas as Core Based Statistical Areas (CBSAs). There is
extensive demographic information available for these areas, and Neustar provides
these to help customers understand the demographics of their populations. There
are currently approximately 1000 CBSAs covering approximately 93% of the
United States population.
Carrier
Airband
The Carrier field provides the name of the organization that owns the Autonomous
Communications System Number (ASN). This field provides a more readable representation of
Inc.
information than the information provided in the ASN field.
ASN
18990
Connection Fixed
Type
Wireless
The ASN is a globally unique number assigned to a group of networks administered
by a single entity such as an ISP or very large organization. Using the ASN
provides more consistency than using an ISP name because while ISP names and
ownerships change, ASNs remain static.
Users can connect to the Internet in several different ways. Neustar categorizes
connections into the following types:
• Dialup
• Cable, DSL
• Fixed Wireless
• Mobile Wireless
• Satellite
• ISDN
• Frame Relay
• OCX (Optical Connections, that is fiber optics)
• TX (leased lines, that is T1, T2, T3 and T4)
Connection Medium
Speed
The connection speed is based on the connection type, Neustar indicates the speed
of the connection to the Internet into high, medium, or low.
Special
Routing
Type
The special routing type is an indication of what kind of Internet Routing Type
(IPRT) designation Neustar has for the IP address. A Yes means that the IP address
is associated with an IPRT that suggests the user could be in a different location
than the IP address. For example, an IPRT of "regional proxy" indicates that the
user could be anywhere in the country, so the Special Routing Type is Yes.
No
Location Services API Programming Reference Guide
PN OL-30024-03
15
Application Programming Interface for the Videoscape Location Service
Location Services Application Regions
Location Services Application Regions
The Location Services application regions include the following codes and interfaces:
• Core Location Service Interface
• Custom Zone Definitions
• Zone Definition Interface
• Emergency Alert System
• EAS Location Service Interface
Core Location Service Interface
The core LS interface uses the HTTP GET Location parameters to return LS client requested information.
Get Location - HTTP GET
The HTTP GET command returns geolocation data for the TARGET based on information from its data
sources. The LS Client must specify the IP address of the TARGET.
The LS Client may optionally request the LS to return matching zone information. The LS Client must specify
either the Zone Group Namespace, Zone Group Classifier, or a flag indicating the LS should search all Zone
Groups.
The Location Service first searches the SP Subnet File followed by the 3rd party geolocation data in order to
find the TARGET IP address. The response indicates whether or not the location data was found. Future
versions of this interface may indicate whether the search is in progress (such as for a mobile location lookup).
If the location is available, the location data specifies a combination of civic, geodetic, and network location
data. The network location is only “on net” if SP Subnet Data has been provided. If the TARGET is “on net”,
the Location Service returns the OnNetName specified in the SP Subnet Data. Otherwise, the Location Service
returns the value as “OFFNET”.
If the LS Client requested Zone data, and matching Zones were found, the LS returns the list of matching
Zones in the response.
The response data may be cached by the LS Client if the response includes the HTTP header Cache-Control:
max-age. This value indicates the maximum duration, in seconds, that the LS Client can cache the results.
Format
http://<hostname>/loc/ipvideo/Location?<name>=<value>&...
Request
The following table provides a list of query parameters:
Query
Parameters
Type
R/O
Description
IpAddress
String
R
IP address of the TARGET.
ZoneNamespace String
O
Namespace of the desired Zone Group.
Location Services API Programming Reference Guide
16
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Core Location Service Interface
Query
Parameters
Type
R/O
Description
ZoneClassifier
String
O
Classifier associated with a Zone Group definition.
O
Flag requesting the LS to return all matching Zone information
from all Zone Groups. By default, this value is false.
AllZoneGroups Boolean
Request Example
GET /loc/ipvideo/Location?IpAddress=64.102.249.8 HTTP/1.1
GET /loc/ipvideo/Location?IpAddress=64.102.249.8&
ZoneNamespace=cisco.adzone3 HTTP/1.1
Request Response - Codes
The following is a list request responses:
• 200 - OK
• 400 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data with the location information. The root element is Location,
as shown below.
The Location Service returns a 404 Not Found if the specified TARGET IP address is not in any of its databases.
For all other errors, the Location Service returns an appropriate HTTP status code.
Element: Location
Children: ZoneMatch (0..N)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
onNet
String
R
Indicates whether the TARGET is on Service Provider's network. If "on
net", the LS returns the OnNetName from the SP Subnet Data. Otherwise,
the LS returns "OFFNET".
countryCode String
R
Two character country code, based on ISO 3166.
state
String
O
Abbreviation for the State or Province.
city
String
O
Name of the City.
metroCode
Integer
O
Metro code assigned to the City.
msa
Integer
O
US Metropolitan Statistical Area
postalCode
String
O
Postal code or zip code associated with the city. Although many cities
have more than one postal code, the geolocation data may only use a single
postal code per city. For Canada, the postal code may be only the first 3
characters.
asn
Integer
O
Autonomous System Number (ASN) identifies the network operator, such
as an ISP. When using MaxMind, a separate MaxMind ASN database
must be loaded.
Location Services API Programming Reference Guide
PN OL-30024-03
17
Application Programming Interface for the Videoscape Location Service
Core Location Service Interface
Attribute
Type
R/O
Description
ispName
String
O
ISP Name or organization owning the ASN. For MaxMind, this is only
provided if ISP name data is specifically configured to be loaded into LS.
connectionType String
O
Type of network connection. Examples include “cable” and “isdn”.
connectionSpeed String
O
Indicates the estimated performance of the network based on the ISP and
connection method. Valid values include: LOW | MEDIUM | HIGH.
Configuration parameters are used to map the different network types into
the speeds shown previously. This may be used for policy based decisions.
proxyServer String
O
Specifies how the connection is routed through the internet and can be
used to determine how close the user is to the public IP address. Valid
values include: Private, Active, or Suspect. If a value is omitted, the default
value is None.
latitude
Float
O
Latitude in degrees.
longitude
Float
O
Longitude in degrees.
locationName String
O
Name of the location specified in the Service Provider subnet file.
ipAddressStart String
R
Geolocation data is tracked by IP address range. Thus, all IP addresses in
that range have the same geolocation data. This is the starting IP address
of that range.
ipAddressEnd String
R
Geolocation data is tracked by IP address range. Thus, all IP addresses in
that range have the same geolocation data. This is the ending IP address
of that range.
The following ZoneMatch element is only included if the LS Client specified the Zone Group matching criteria
and if the LS determined that the TARGET was within a Zone Group that was identified in the request (or
any Zone Group if all Zone Groups were requested). There is one ZoneMatch element for each matching
Zone. Multiple ZoneMatch elements may have the same namespace if the Zone Group has overlapping Zones
and the TARGET resides within his overlapping region.
Element:ZoneMatch
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
namespace String
R
Namespace of the Zone Group.
name
R
Name of the matching Zone, within the Zone Group identified by the
namespace.
String
The following are example responses.
No Zones
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 225
Location Services API Programming Reference Guide
18
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Zone Definition Interface
Cache-Control: Max-Age=3600
<ns2:Location
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc"
asn="109"
city="san jose"
connectionSpeed="high"
connectionType="tx"
countryCode="us"
ipAddressEnd="171.71.150.1"
ipAddressStart="171.71.150.1"
latitude="37.33053"
longitude="-121.83823"
metroCode="807"
msa="41940"
onNet="OFFNET"
postalCode="95122"
proxyServer="fixed"
state="ca"/>
</ns2:Location>
Matching Zone
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 225
Cache-Control: Max-Age=3600
<ns2:Location
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc"
asn="109"
city="San Leandro"
countryCode="US"
ipAddressEnd="171.71.150.255"
ipAddressStart="171.71.150.0"
latitude="37.7156"
locationName="4232"
longitude="-122.1602"
metroCode="807"
msa="0"
onNet="OFFNET"
postalCode="94577"
state="CA">
<ZoneMatch nameSpace="cisco.adzone3" name="city_segment"/>
<ZoneMatch nameSpace="us_regions" name="west_oast"/>
</ns2:Location>
Zone Definition Interface
Zone Definition interface provides a means to authenticate operators. This interface assumes that the Zone
Definitions will be configured by an administrator for the Service Provider.
The Zone Definition interface uses the following commands:
• Get Provider Name List
• Get Zone Group List
• Get Zone Group
• Get Zone
Get Provider Name List
The HTTP GET command used with this command returns a list of Providers defined on the Location Service.
Location Services API Programming Reference Guide
PN OL-30024-03
19
Application Programming Interface for the Videoscape Location Service
Zone Definition Interface
Format
http://<hostname>/loc/zone/ProviderNameList
Request Example
GET /loc/zone/ProviderNameList HTTP/1.1
Request Response - Codes
The following is a list of HTTP Status Code responses:
• 200 - OK
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data with a list of provider names. The root element is
ProviderNameList, as shown below.
The LS returns a 404 Not Found if no providers are defined.
For all other errors, the LS returns an appropriate HTTP status code.
Element:ProviderNameList
Children: ProviderName (1..N)
Element:ProviderName
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
String
R
Unique name of the Provider.
The following is an example response.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 213
<ProviderNameList
xmlns="urn:com:cisco:videoscape:conductor:loc">
<ProviderName>cisco</ProviderName>
<ProviderName>company2</ProviderName>
<ProviderName>company5</ProviderName>
</ProviderNameList>
Get Zone
The HTTP GET command used with this command returns a specific Zone definition. The LS returns the
Zone definition details, including all of the location definitions that comprise the Zone.
Format
http://<hostname>/loc/zone/Zone?<name>=<value>&...
The following table provides a list of attributes that are associated with this element.
Location Services API Programming Reference Guide
20
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Zone Definition Interface
Attribute
Type
R/O
Description
Provider
String
R
The provider that defined the Zone Group.
ZoneGroup String
R
The name of the Zone Group.
Zone
R
Name of the Zone.
String
Request Example
GET /loc/zone/Zone?Provider=cisco&ZoneGroup=adzone3&Zone=region1 HTTP/1.1
Request Response - Codes
The following is a list of HTTP Status Code responses:
• 200 - OK
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data, with the complete definition for the requested segment.
The root element is Zone, which is detailed in the Zone Import File Format, on page 10 section of this guide.
The LS returns a 404 Not Found if the specified Zone cannot be found.
For all other errors, the LS returns an appropriate HTTP status code.
The following is an example response.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 242
<Zone
xmlns="urn:com:cisco:videoscape:conductor:loc"
name="region1">
<MetroCode>504</MetroCode>
<MetroCode>512</MetroCode>
<MetroCode>511</MetroCode>
<PostalCode>19101</PostalCode>
<PostalCode>18936</PostalCode>
</Zone>
Get Zone Group
The HTTP GET command used with this command returns a specific Zone Group definition. The LS Client
must specify both the Provider and Zone Group names. The LS returns all classifiers and all zones associated
with the specified Zone Group.
Format
http://<hostname>/loc/zone/ZoneGroup?<name>=<value>&...
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
Provider
String
R
The provider that defined the Zone Group.
ZoneGroup String
R
The name of the Zone Group.
Location Services API Programming Reference Guide
PN OL-30024-03
21
Application Programming Interface for the Videoscape Location Service
Zone Definition Interface
Request Example
GET /loc/zone/ZoneGroup?Provider=cisco&Zone=adzone3 HTTP/1.1
Request Response - Codes
The following is a list of HTTP Status Code responses:
• 200 - OK
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data, with the complete definition for the requested Zone
Group. The root element is ZoneGroup, which is detailed in the Zone Import File Format, on page 10 section
of this guide.
The LS returns a 404 Not Found if no Zone Group cannot be found.
For all other errors, the LS returns an appropriate HTTP status code.
The following is an example response.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 561
<ZoneGroup
xmlns="urn:com:cisco:videoscape:conductor:loc"
name="ad_zone_3"
provider="cisco">
<Classifier type="regex">
/http:\/\/cdn\.cisco\.com.*/
</Classifier>
<Zone name="region1">
<MetroCode>504</MetroCode>
<MetroCode>512</MetroCode>
<MetroCode>511</MetroCode>
<PostalCode>19101</PostalCode>
<PostalCode>18936</PostalCode>
</Zone>
<Zone name="region2">
<CountryCode>CA</CountryCode>
</Zone>
<Zone name="region3">
<State>NY</State>
<State>MA</State>
<MetroCode>506</MetroCode>
</Zone>
</ZoneGroup>
Get Zone Group List
The HTTP GET command used with this command returns a list of Zone Group names. The LS Client may
specify a Provider name to filter the list based on a specific content or service provider. If no provider is
specified, then all Zone Group names are returned.
Note that only the Provider and Zone Group names are returned in the list. The list does not contain the actual
Zone definitions.
Format
http://<hostname>/loc/zone/ZoneGroupList?<name>=<value>&...
The following table provides a list of attributes that are associated with this element.
Location Services API Programming Reference Guide
22
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Zone Definition Interface
Attribute
Type
R/O
Description
Provider
String
R
Optional name of the provider. If specified, the LS only returns Zone Group
names for the specified Provider.
Request Example
GET /loc/zone/ZoneGroupList?Provider=cisco HTTP/1.1
Request Response - Codes
The following is a list of HTTP Status Code responses:
• 200 - OK
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data with a list of Zone Group names and associated providers.
The root element is ZoneGroupList, which is detailed in the Zone Import File Format, on page 10 section of
this guide. Note that the ZoneGroup elements do not have any child elements associated with them.
The LS returns a 404 Not Found if no Zone Groups are defined that match the specified criteria.
For all other errors, the LS returns an appropriate HTTP status code.
The following is an example response.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 185
<ZoneGroupList
xmlns="urn:com:cisco:videoscape:conductor:loc">
<ZoneGroup name="adzone3" provider="cisco"/>
<ZoneGroup name="peering_zone" provider="cisco"/>
</ZoneGroupList>
Create Classifiers
The HTTP POST command, used with this command, is used to create or replace all classifiers for a particular
Zone Group. If this method is called and the Zone Group namespace does not exist, then the Zone Group
namespace is created. All previous classifiers associated with this Zone Group are replaced by the specified
list of classifiers. If no classifiers are specified in the request, the LS deletes all classifiers associated with the
Zone Group.
Format
http://<hostname>/loc/zone/Classifiers
Request Elements
The request must include the ZoneGroup element as the root element and all Classifier child elements as
defined in the Zone Import File Format, on page 10 section of this guide.
Note
The request cannot include any Zone elements.
Request Example
POST /loc/zone/Classifiers HTTP/1.1
Content-Type: application/xml
Location Services API Programming Reference Guide
PN OL-30024-03
23
Application Programming Interface for the Videoscape Location Service
Emergency Alert System
Content-Length: 238
<ZoneGroup
xmlns="urn:com:cisco:videoscape:conductor:loc"
name="asn_zone"
provider="provider2">
<Classifier type="simple">images.provider2.com</Classifier>
<Classifier type="simple">cdn.provider2.com</Classifier>
</ZoneGroup>
Request Response - Codes
The following is a list of HTTP Status Code responses:
• 204 - No Content
• 403 - Forbidden
• 500 - Internal Server Error
No XML data is included in the response. On a successful response (204 No Content), the response only
consists of the HTTP header.
The LS returns a 403 Forbidden if the LS Client is not authorized to create/replace classifiers for the specified
provider.
For all other errors, the LS returns an appropriate HTTP status code.
Emergency Alert System
The Emergency Alert System (EAS) is country specific. The following are the currently supported codes:
• United States - uses a FIPS code, which is based on state and county boundaries.
• Canada - uses the Standard Geographical Classification (SGC) code.
FIPS State and Territory Code
The United States EAS message system uses the FIPS State and Territory code format. A FIPS code is a
5-digit number that consists of a 2-digit state code, followed by a 3-digit county code. A complete list of FIPS
codes can be found at http://www.itl.nist.gov/fipspubs/co-codes/states.htm.
In some cases, it is easier to map a Client location using a zip code instead of a county. A mapping of zip code
to FIPS code can be extracted from a 1999 database, located at
http://www.census.gov/geo/www/tiger/zip1999.zip. Note that this information can be out of date, as zip codes
are added or change more frequently than counties.
The LS supports a lookup of FIPS code based on county and zip code. When specifying a county as the key,
the LS Client must also specify the associated state, since county names are not unique across states. The LS
returns a single FIPS code when the LS Client specifies a county. Zip codes can span county boundaries. In
fact, a zip code may span up to 5-counties. If you are using a zip code as the key, the LS returns all of the
FIPs codes associated with the counties that intersect that zip code.
As previously stated, a zip code may span multiple EAS regions. The Client Directory obtains the set of EAS
regions from the LS, based on locality. The Client Directory then makes a Client subscription request to the
Alert Manager for each of these EAS regions. The mapping of county to FIPS code is generally static. There
is one FIPS code per county. The mapping of zip code to FIPS code is also relatively static, although the US
Postal Service does occasionally adjust the zip code to county mapping. The ZIP*Data™ product provides a
zip code to county and FIPS mapping. In the ZIP*Data™ product, the County Name Database provides a
Location Services API Programming Reference Guide
24
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Emergency Alert System
mapping of FIPS code to county name while the Zip/County Database provides the mapping of 5 digit zip
code to FIPS code.
The ZIP*Data™ product is updated monthly. The LS provides an import capability to reload the data when
an updated data file is deployed onto the system. Note that this is a non-service impacting import. The LS
loads the latest data in the background, validates it, and then begins using it without requiring a restart. The
format of the relevant databases in ZIP*Data™ data is shown below.
The highlighted fields will be used by the Location Service to populate its Location Data Cache. Note that
the data is supplied per zip code. A zip code may appear multiple times since it may map to multiple counties.
These import files will be in ASCII format with fixed length records.
The ASCII file is named "cnty.dat". The format of each line of the County Name Database in the ZIP*Data™
product is shown in the table below and is supplied per zip code. Each record is terminated by a CR/LF.
Field
Type
Length
Description
FIPS Code
*
Numeric
5 digits
County FIPS Code
County
Name *
String
25 chars
County Name
State
String
2 chars
State abbreviation
Time Zone
Numeric
2 digits
Number of hours past GMT
County
Type
String
1 char
Code describing the county
County Seat String
28 chars
County government capital
Name Type String
1 char
Code assigned to the name of the county
Elevation
Numeric
5 digits
Elevation of county seat in feet above sea level
Persons Per Numeric
HH
4 digits
Average number of persons per household, last two digits are decimal
digits
Population
Numeric
8 digits
Estimated county population
Area
Numeric
8 digits
County area in square miles
Households Numeric
8 digits
Number of households in the county
White
Numeric
8 digits
Estimate of White population in county
Black
Numeric
8 digits
Estimate of Black population in county
Hispanic
Numeric
8 digits
Estimate of Hispanic population in county
Avg
Income
Numeric
8 digits
Average annual household income
Avg House Numeric
Value
8 digits
Average value of a home within the county
CR/LF
2 chars
Carriage return / line feed
EOL
Location Services API Programming Reference Guide
PN OL-30024-03
25
Application Programming Interface for the Videoscape Location Service
Emergency Alert System
* Fields are used by the LS to populate its Location Data Cache.
The following is an example with several records.
42015BRADFORD
24453
61471
42017BUCKS
218725 552588
42019BUTLER
65862 170302
42021CAMBRIA
60531 146183
251
19495
1367
4322
PA 5CTOWANDA
33723
51500
PA 5ADOYLESTOWN
14005
55244 139000
PA 5CBUTLER
1016
41654
62800
PA 5BEBENSBURG
1352
29755
39500
C
7372.57
62761
1151
C
3402.73
597635
608
C 10112.64
174083
789
C 21402.52
152598
688
398
The ASCII file is named zipcnty.dat. The format of each line of the County - ZIP Code Database™ data is
shown in the following below. Note that each record is terminated by CR/LF.
Field
Type
Length
Description
Zip Code
Numeric
5 digits
Zip Code
FIPS Code Numeric
5 digits
County FIPS Code
Percentage String
6 chars
Percentage of deliverable addresses that reside in a county FIPS code
for a ZIP Code. Last two digits are decimal positions.
Count
Numeric
6 digits
Number of records used to determine the percentage.
CR/LF
EOL
2 chars
Carriage return / line feed
For example:
1945442017 13.59
1945442091 86.41
1945542091100.00
1945642091100.00
1945742029100.00
1946042029 92.65
389
2474
2
188
69
3429
Standard Geographical Classification Codes
The Canadian alerting systems utilize codes defined in the Standard Geographical Classification (SGC). The
SGC codes are made up of a one to ten digit value. Numbers are assigned from a regional level all the way
down to a metropolitan area. The layout of an SGC code and an example is as follows.
SGC Format
X = Region, example 2 = Quebec
XY = Province or Territory, example 24 = Quebec
XY ZZ = Census Division, example 24 66 = Montreal
XY ZZ AAA = Census Subdivision, example 24 66 102 = Kirkland
XY ZZ AAA BBB = Census Metropolitan Area, example 24 66 102 462 Kirkland V (where V indicates
‘ville’ and French only)
Official information about the Canadian SGC system can be found at the Statistic Canada website:
http://www.statcan.gc.ca/subjects-sujets/standard-norme/sgc-cgt/2011/sgc-cgt-intro-eng.htm.
According to CAP-CP, the SGC codes used extends only to the Census Subdivision level (that is, the "XY
ZZ AAA" level) thus only seven digits of the SGC is required to be supported in the current EAS solution.
Location Service supports a lookup of SGC by postal code. In Canada, a Postal Code is a six-character code
in the form "ANA NAN", where "A" is an alphabetic character and "N" is a digit (for example, K1A 0T6).
These codes are defined and maintained by Canada Post Corporation (CPC). Postal Codes can span multiple
Location Services API Programming Reference Guide
26
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Emergency Alert System
geographic regions, including provinces in some cases, so the Location Service returns a list of all matching
SGC codes.
The source data for the Canadian Postal Code -> SGC Mapping is the "Postal Code Conversion File (PCCF)"
provided by © Statistics Canada, 2011 (Catalogue no. 92-153-G). The files in this product map CPC Postal
Codes to Statistics Canada's standard geographic areas for which census data and other statistics are produced.
The PCCF contains files in both English and French but only English data is used. The Location Service only
loads the Postal Code to SGC mapping from the files at this time, which is not language specific. Updates to
the PCCF are made available semi-annually.
The PCCF contains a national file for all of Canada as well as mapping files for individual provinces. The
Location Service uses the pccfNat (national) which is an ASCII file with fix-length records terminated by a
CR/LF. The format of the file is shown below with fields used by the Location Service highlighted in the
following table:
Field
Type
Length
Description
Postal Code
String
6 characters
The postal code.
FSA
String
3 characters
The forward sortation area.
PR
String
2 characters
The province/territory code.
CDuid
String
4 characters
The census division unique identifier.
CSDname
String
7 characters
The census subdivision unique identifier.
CSDname
String
70 characters
The census subdivision name.
CSDtype
String
3 characters
The census subdivision type.
CCScode
String
3 characters
The census consolidated subdivision code.
SAC
String
3 characters
The statistical Area Classification code (includes
CMA/CA).
SACtype
String
1 characters
The statistical Area Classification type (includes
CMA/CA).
CTname
String
7 characters
The census tract name.
ER
String
2 characters
The economic region code.
DPL
String
4 characters
The designated place code.
FED01uid
String
5 characters
The federal electoral district - 2003 Representation
Order unique identifier.
POP_CNTR_RA
String
4 characters
The population center/rural area code.
POP_CMTR_RA_type String
1 characters
The population center/rural area type.
DAuid
String
8 characters
The dissemination area unique identifier.
Dissemination block String
2 characters
The dissemination block code.
Rep_Pt_Type
1 characters
The representative point type.
String
Location Services API Programming Reference Guide
PN OL-30024-03
27
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Field
Type
Length
Description
LAT
Numeric
11 digits
The latitude of lowest level geographic area for
postal code record (as indicated in Rep_point
variable).
LONG
Numeric
13 characters
The longitude of lowest level geographic area for
postal code record (as indicated in Rep_point
variable).
SLI
String
1 characters
The single link indicator.
PCtype
String
1 characters
The postal code type.
Comm_Name
String
30 characters
The community name.
DMT
String
1 characters
The delivery mode type.
H_DMT
String
1 characters
The historic Delivery mode type.
Birth_Date
String
8 characters
The birth date, in a yyyymmdd format.
Ret_Date
String
8 characters
The retired date, in a yyyymmdd format.
PO
String
1 characters
The delivery installation.
QI
String
3 characters
The quality indicator.
Source
String
1 characters
The source of geocoding.
POP_CNTR_RA_SIZE_CLASS String
1 characters
The population center and rural area classification.
EAS Location Service Interfaces
The EAS Location Service's interfaces use the HTTP GET EAS Location parameters to return LS client
country specific requested information. The Location Service does not validate XML namespaces on EAS
related requests, as the Controllers do not support namespaces. However, the Location Service does insert the
XML namespace in the EAS responses.
Get EAS Location - HTTP GET
The HTTP GET command returns a list of EAS codes associated with a TARGET location. Since EAS is
country specific and may have multiple keys that can be used to locate the EAS region, the LS Client must
specify query parameters that identify the EAS type and lookup method.
The LS Client must indicate the type of EAS data that it requires. This can be done by specifying either the
country code or the EAS type. If specifying a country code, the following mapping of country code to EAS
type is used:
• United States - FIPS
• Canada - SGC
Location Services API Programming Reference Guide
28
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
No other country code has default mapping. Therefore, for other countries, the LS Client must explicitly
specify the EAS type. Typical EAS types include "FIPS" and "SGC". The data import for the Explorer
Controller EAS mapping provides support for other EAS types to support other countries.
The Location Service supports a number of different lookup methods to obtain the EAS codes. The supported
lookup methods include:
• County Name - Used to obtain the FIPS code in the US
• Postal Code or Zip Code
• Out of Band Bridge - EAS support for ECs for settop boxes and CableCARDs
• Multicast Group Address - EAS support for DTACS for DTAs
• Multicast Group Name - EAS support for DTACS for DTAs
The following table shows the different lookup methods and the query parameters that the LS Client must
supply:
Lookup
Method
State
County
County
X
X
Postal
Code
PostalCode Controller
Id
OOBBId
GroupAddress GroupName
X
Out of
Band
Bridge
X
Multicast
Group
Address
X
Multicast
Group
Name
X
X
X
X
In order to support EAS for IP client devices, the LS Client cannot supply an IP Address to obtain the EAS
region. The primary reason is that IP address to location typically provides city level accuracy for the IP client
location. This is insufficient for EAS purposes. Therefore, the LS Client should consult a subscriber database
(such as UPM or Client Directory) to obtain the locality information.
The Location Service only searches its internal databases associated with the specified EAS type or country
code (which maps to a default EAS type). Therefore, if country code or EAS type is omitted, or an unsupported
country code or unknown EAS type is specified, the Location Service will return an error.
If the LS Client does not specify the parameters required for a particular lookup method, the Location Service
will return an error.
If the LS Client supplies query parameters such that multiple lookup methods are in play, then the LS will
only select one of the lookup methods (based on whatever is programmed into the LS) and return the EAS
codes for that particular method. (In other words, the LS Client needs to supply only the required query
parameters for a particular lookup method or unexpected results may be returned.)
Location Services API Programming Reference Guide
PN OL-30024-03
29
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
The response data may be cached by the LS Client if the response includes the HTTP header Cache-Control:
max-age. This value indicates the maximum duration in seconds that the LS Client can cache the results.
Format
http://<hostname>/loc/ipvideo/Locality2EAS?<name>=<value>&...
Request
The following table provides a list of query parameters:
Query
Parameters
Type
R/O Description
CountryCode
String
O
The two character country code based on ISO 3166 specified in the request.
The country code defines the type of EAS data that will be returned: US
->FIPS CA ->SGC. Either CountryCode or EASType needs to be specified.
EASType
String
O
The type of EAS data to return. Typical values include: FIPS, SGC, or
Other (value depends on country).
Either CountryCode or EASType needs to be specified. If both are specified,
EASType takes precedence.
State
String
O
Two character state abbreviation, as specified in the Zip-Data-manual.
County
String
O
Name of the county (used to lookup FIPS code). This data is case insensitive.
PostalCode
Note
Postal code or zip code. US zip codes are truncated to 5 digits (since that
is the zip code size from the data source).
ControllerId
Integer R
Id of controller.
This value must be specified if either OOBBId or GroupAddress is specified.
OOBBId
Integer O
Out of band bridge Id. This value is used for settop boxes and CableCARDS.
GroupAddress
String
O
Mutlicast group address. This value is used for DTAs.
SourceAddress String
O
Address of the multicast source. This value is only used for IPv6 and DTAs.
GroupName
O
Alternate method to search for EAS codes associated with a multicast. This
is used for DTAs.
String
All query parameters of type String are case insensitive.
Request Example - Postal Code
GET /loc/eas/Locality2EAS?CountryCode=US&PostalCode=18951 HTTP/1.1
Request Example - County
GET /loc/eas/Locality2EAS?EASType=FIPS&State=PA&County=Montgomery HTTP/1.1
Request Example - Out of Band Bridge ID
GET /loc/eas/Locality2EAS?CountryCode=CA&ControllerId=11&OOBBId=142 HTTP/1.1
Request Example - Multicast Group Address
GET /loc/eas/Locality2EAS?CountryCode=CA&ControllerId=11&GroupAddress=228.1.1.3 HTTP/1.1
Request Example - Multicast Group Name
GET /loc/eas/Locality2EAS?CountryCode=CA&ControllerId=11&GroupName=BSG6 HTTP/1.1
Location Services API Programming Reference Guide
30
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Request Response - Codes
The following is a list request responses:
• 200 - OK
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the LS returns XML data with a list of EAS locations associated with the specified
locality. The root element is EASLocation, as shown below.
If the request is missing the country code or EAS type or an unsupported country code is specified, the LS
returns a 400 Bad Request response. If the request is missing query parameters such that a valid lookup method
cannot be determined, the LS returns a 400 Bad Request response.
The Location Service returns a 404 Not Found if the locality ID is not in the EAS database associated with
the specified country code and locality type.
For all other errors, the Location Service returns an appropriate HTTP status code.
Element: EASLocation
Children: EASRegion (1..N)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
dataType
String
R
Type of EAS Region. Valid values include:
FIPS | SGC
Other EAS types may be returned if those were specified in the EAS import
file for the Explorer Controller.
Element:EASRegion
Children: None
The following table provides a list of attributes that are associated with this element.
Type
R/O
Description
String
R
EAS region identifier:
FIPS - value is the 5 digit FIPS code
SGC - value is the 6 digit SGC code
Other - Depends on import file
Note that ZIP*Data only provides a 5 digit FIPS code but the EAS import file for
the Explorer Controller can specify a 6 digit FIPS code.
The following are example responses.
Location Services API Programming Reference Guide
PN OL-30024-03
31
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
FIPS
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 164
Cache-Control: Max-Age=3600
<EASLocation
xmlns="urn:com:cisco:videoscape:conductor:loc"
dataType="FIPS">
<EASRegion>42017</EASRegion>
<EASRegion>42091</EASRegion>
</EASLocation>
SGC
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 202
Cache-Control: Max-Age=3600
<EASLocation
xmlns="urn:com:cisco:videoscape:conductor:loc"
dataType="SGC">
<EASRegion>1002010</EASRegion>
<EASRegion>1107001</EASRegion>
<EASRegion>1107003</EASRegion>
</EASLocation>
Get EAS Alert Target
The Get EAS Alert Target method is used to obtain a list of EAS Alert Targets (for example, OOBB or
multicasts). This can be used by the UI to obtain a list of Alert Targets by Controller in order to populate the
UI to allow the operator to specify the EAS Code mappings.
This can also be used by the ECS to obtain the EAS Alert Targets for a specific EAS Code or a list of EAS
Codes. The operator must have already configured the Alert Target to EAS Code mapping using the UI. See
the Set EAS Alert Target Map for additional details.
The query may include a wildcard to match a group of EAS Codes. This is particularly useful when an EAS
occurs for a large region. A wildcard consists of appending an "*" to an EAS Code. For example, an EAS
Code of "01*" matches all EAS Codes that begin with the string "01".
Multiple EAS targets may be returned. These targets may cover regions managed by different Controllers.
EAS targets in the response are aggregated by Controller.
The response data may be cached by the LS Client if the response includes the HTTP header Cache-Control:
max-age. This value indicates the maximum duration in seconds that the LS Client can cache the results.
Format
http://<hostname>/loc/eas/EASAlertTargets?<name>=<value>&...
Request
The following table provides a list of query parameters:
Query
Parameters
Type
R/O Description
ControllerId
Integer O
Id of controller.
This value must be specified to get EAS Alert Targets from controller.
Location Services API Programming Reference Guide
32
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Note
Query
Parameters
Type
R/O Description
EASType
String
O
EAS Type: Valid values include: FIPS, SGC, and other (depending on
mapping).
This value must be specified to get EAS Alert Targets mapped to an EAS
Code.
EASCode
String
O
EAS Region Identifier: Valid values include: FIPS (value is the 5-6 digit
FIPS code), SGC (value is the 1-7 digit SGC code), and other (depending
on mapping).
This value must be specified to get EAS Alert Targets mapped to an EAS
Code. The caller may include an '*' in the EASCode as a wildcard and the
caller may supply multiple EASCode parameters. However, the caller must
include an EASType parameter.
All string based query parameters are case insensitive.
Request Example - Controller
GET /loc/eas/EASAlertTargets?ControllerId=12 HTTP/1.1
Request Example - EAS Code
GET /loc/eas/EASAlertTargets?EASType=SGC&EASCode=1107003 HTTP/1.1
Request Example - EAS Code with Wildcard
GET /loc/eas/EASAlertTargets?EASType=SGC&EASCode=01* HTTP/1.1
Request Example - List of EAS Codes
GET /loc/eas/EASAlertTargets?EASType=SGC&EASCode=0101233&EASCode=0102118&EASCode=0123*
HTTP/1.1
Request Response - Codes
The following is a list request responses:
• 200 - OK
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the Location Service returns XML data with a list of EAS Alert Targets associated
with the specified Controller, EAS Code, list of EAS codes, or EAS Code wildcard. The root element is
EASAlertTargets shown below. EAS Targets are grouped by Controller. Note that if specifying a list of EAS
codes or a wildcard, the response does not indicate which EAS targets are associated with individual EAS
codes in the request.
If the request is missing query parameters such that a lookup cannot be performed, the LS returns a 400 Bad
Request response.
The Location Service returns a 404 Not Found if a match cannot be found for the specified Controller or EAS
Code.
For all other errors, the Location Service returns an appropriate HTTP status code.
Location Services API Programming Reference Guide
PN OL-30024-03
33
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Element: EASAlertTargets
Children: Controller (1..N)
Element: Controller
Children: OOBBList (0..1)
MulticastList (0..1)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O Description
Id
String
R
Unique Name or ID of this Controller. Note that DTACS does not support
exporting data for EAS. Therefore, both OOBB and Multicast data are
associated with ECs.
desc
String
O
Optional description of the controller. Limited to 255 bytes.
Element: OOBBList
Children: OOBB (0..N)
Element: OOBB
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O Description
Id
Integer R
The Id of the out of band bridge. The OOBB Id is unique for a given
controller.
name
String
R
The name of the OOBB. Limited to 255 bytes.
type
String
O
Specifies the OOBB type. Valid values include:
• Unknown
• QPSK
• DSG
• CMTS
The default value Unknown is used, when no value is specified.
forceTuneSourceId Integer O
Source ID to use for EAS force tune operations. The default value is 0,
when not specified.
Element: MulticastList
Children: Multicast (0..N)
Element: Multicast
Children: None
The following table provides a list of attributes that are associated with this element.
Location Services API Programming Reference Guide
34
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Attribute
Type
R/O Description
groupAddress
String
R
Multicast group address. This may be IPv4 or IPv6.
sourceAddress
String
O
If using IGMPv3, the controller may specify the address of the multicast
source. This may be IPv4 or IPv6.
groupName
String
O
Optional name of the multicast. This may be a broadcast service group
name. The name is limited to 255 bytes.
The following are example responses.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 276
Cache-Control: Max-Age=3600
<ns2:EASAlertTargets
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
<Controller id="EC3">
<OOBBList>
<OOBB id="14" name="qpsk1" type="QPSK" forceTuneSourceId="1011"/>
<OOBB id="15" name="qpsk3" type="QPSK" forceTuneSourceId="4026"/>
</OOBBList>
<MulticastList>
<Multicast groupAddress="231.22.1.4" groupName="BSG1"/>
</MulticastList>
</Controller>
<Controller id="EC9">
<MulticastList>
<Multicast groupAddress="231.21.0.3" groupName="BSG6/>
<MulticastList>
</Controller>
</ns2:EASAlertTargets>
Get EAS Alert Target Map
This Get EAS Alert Target Map method is used to obtain the mapping of a single EAS Alert Target to a set
of EAS Codes. This is used by the UI for configuring the mapping of EAS Code to target region. The caller
must specify the Controller and either the OOBB or Multicast information. A Controller ID must be specified,
as the OOBB and Multicast data may be scoped by the Controller. The UI must then specify either the OOBB
ID or Group Address. Note that if the system is using IGMPv3 and the UI is querying for the multicast
mapping, the UI must also specify the source address of the multicast.
The Location Services returns a complete list of EAS codes that are currently mapped to the specified alert
target.
Format
http://<hostname>/loc/eas/EASAlertTargetMap?<name>=<value>&...
Request
The following table provides a list of query parameters:
Query
Parameters
Type
R/O Description
ControllerId
Integer R
Id of controller.
This value must be specified to get EAS Alert Targets from controller.
Location Services API Programming Reference Guide
PN OL-30024-03
35
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Note
Query
Parameters
Type
OOBBId
Integer O
Out of band bridge Id. This parameter may be used for QPSK, DSG, and
CMTS bridges.
GroupAddress
String
O
Mutlicast group address. This value is used for DTAs.
SourceAddress String
O
Address of the multicast source. This value only needs to be specified using
IGMP3. This value is used for DTAs.
GroupName
O
Alternate method to search for EAS codes associated with a multicast. This
value is used for DTAs.
String
R/O Description
All query parameters of type String are case insensitive.
Request Example - OOBB
GET /loc/eas/EASAlertTargetMap?ControllerId=EC12&OOBBId=4 HTTP/1.1
Request Example - Multicast Group Address
GET /loc/eas/EASAlertTargetMap?ControllerId=6&GroupAddress=228.0.23.1 HTTP/1.1
Request Example - Multicast Group Name
GET /loc/eas/EASAlertTargetMap?ControllerId=6&GroupName=BSG6 HTTP/1.1
Request Response - Codes
The following is a list request responses:
• 200 - OK
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the Location Service returns XML data with a list of EAS codes that have been
mapped to the target region. The root element is EASAlertTargetMap shown below. Note that it is valid for
the LS to return zero EASCode elements. This simply indicates that no mapping information exists for this
alert target.
If the request is missing query parameters such that a lookup cannot be performed, the LS returns a 400 Bad
Request response.
The Location Service returns a 404 Not Found if a match cannot be found for the specified alert target (OOBB
or Multicast) associated with the specified Controller.
For all other errors, the Location Service returns an appropriate HTTP status code.
Element: EASAlertTargetMap
Children: Controller (1..N)
OOBB (1) and Multicast
EASCode (0..N)
The Controller, OOBB, and Multicast elements are defined in the Get EAS Alert Targets section of this guide.
Note that no child elements of the Controller element are specified
Location Services API Programming Reference Guide
36
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Element: EASCode
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O Description
countryCode
String
R
Two character country code based on ISO 3166 specified in the request.
The country code defines the type of EAS data that will be returned.
dataType
String
O
EAS Region Type: Valid values include: FIPS, SGC, and other (specified
to support countries). If the data type is omitted, the default data type for
the specified country code is used. The default data for type for the "US"
is "FIPS" and the default data type for Canada is "SGC".
Value
Type
R/O
Description
String
R
EAS Region Identifier:
Valid values include: FIPS (value is the 5-6 digit FIPS code), SGC (value is the 1-7 digit
SGC code), and other (depending on country).
The following are example responses.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 340
<ns2:EASAlertTargetMap
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
<Controller id="EC3"/>
<OOBB id="14"/>
<EASCode countryCode="CA" dataType="SGC">1002010</EASCode>
<EASCode countryCode="CA" dataType="SGC">1107001</EASCode>
<EASCode countryCode="CA" dataType="SGC">1107003</EASCode>
</ns2:EASAlertTargetMap>
Set EAS Alert Targets
The Set EAS Alert Targets method is used by the Controller (EC) to specify the Controller to Alert Target
information. The EC may also specify the multicast information for DTACS since the DTACS does not export
data. The multicast information includes a list of out of band bridge (OOBB) IDs, while the DTACS specifies
a list of multicast groups and optionally multicast source addresses (for IGMPv3 support).
The Controller must supply its complete list of Alert Targets for either OOBB or Multicasts (or both). There
are no incremental updates since this list should be small. If the Controller specifies an OOBBList element,
the LS updates all OOBB elements for that Controller but the Multicasts will not be changed. If the Controller
specifies a MulticastList element, the LS updates all Multicast elements for that Controller but the Controller
is not changed. The Controller can update both OOBB and Multicast elements by specifying both OOBBList
and MulticastList elements.
The Location Service performs a Diff operation, adding new Alert Targets and deleting Alert Targets that
have been removed. The key for locating matching Alert Targets for OOBB and Multicast is OOBB ID and
Multicast Group Address, respectively. Note that since there is no EAS source redundancy, only the Multicast
Location Services API Programming Reference Guide
PN OL-30024-03
37
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Group Address is the key. That is, for a given Controller, the LS should overwrite (G, S1) with (G, S2) as
long as the multicast group address is the same, even if the multicast source address changed.
When deleting an Alert Target, the Location Service will also delete all of the associated EAS codes. For
example, an EC sends a Create EAS Alert Target message with an OOBB ID of 10 in the first message and
the operator assigns an SGC value of 1001200 to that OOBB ID. If the next message from the EC is missing
OOBB ID 10, the LS deletes the OOBB ID 10 along with the associated SGC mapping from its data.
Controllers are automatically added if new Controllers are discovered in the Set EAS Alert Targets list.
However, Controllers are not automatically deleted, since a given Set EAS Alert Targets message typically
only has a subset of Controllers.
Format
http://<hostname>/loc/eas/EASAlertTargets
Request
The root element is EASAlertTargets. This element and its child elements are specified in the Get EAS Alert
Targets section of this guide. Note that only a subset of the Controllers in the system may be listed under an
EASAlertTargets element. This may be due to exporting data from a single EC or having multiple ECS
instances in the system.
The Controller element specifies an EC or DTACS instance. The combination of controller type and controller
ID must be unique.
Request Example - EC with OOBB and Multicast
POST loc/eas/EASAlertTargets HTTP/1.1
Content-Type: application/xml
Content-Length: 204
<ns2:EASAlertTargets
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
<Controller id="EC3">
<OOBBList>
<OOBB id="14" name="qpsk1" type="QPSK" forceTuneSourceId="1011"/>
<OOBB id="15" name="qpsk3" type="QPSK" forceTuneSourceId="4026"/>
</OOBBList>
<MulticastList>
<Multicast groupAddress="231.22.1.4" groupName="BSG1"/>
</MulticastList>
</Controller>
</ns2:EASAlertTargets>
The following is a list request responses:
• 204 - No Content
• 400 - Bad Request
• 500 - Internal Server Error
No XML data is included in the response. On a successful response (204 No Content), the response only
consists of the HTTP header.
For all other errors, the Location Service returns an appropriate HTTP status code.
Get Controller List
The Get Controller List method is used by the UI to obtain a list of Controllers that are currently defined in
the system. The Controllers is created using the method specified in the Set EAS Alert Targets section of this
guide.
The LS returns a complete list of Controllers configured in the system.
Location Services API Programming Reference Guide
38
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
Format
http://<hostname>/loc/eas/ControllerList
Request
There are no parameters for this request.
Request Example
GET /loc/eas/ControllerList HTTP/1.1
Request Example - DTACS
The following is a list request responses:
• 200 - OK
• 500 - Internal Server Error
On a successful response, the Location Service returns XML data with a list of Controllers configured on the
Location Service. The root element is ControllerList shown below. Note that if no Controllers are defined,
the LS returns a list with zero Controller elements.
For all other errors, the Location Service returns an appropriate HTTP status code.
Element: ControllerList
Children: Controller (0 .. N)
The Controller element is defined in the Get EAS Alert Targets section of this guide. Note that no child
elements of the Controller element are returned.
The following is an example responses.
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 167
<ns2:ControllerList
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
<Controller id="3"/>
<Controller id="9"/>
</ns2:ControllerList>
Delete Controller
The Delete Controller method is used by the UI to delete a Controller and all data associated with that Controller.
The caller must supply the Controller ID.
When this request is received, the Location Service deletes the specified Controller, all associated EAS Alert
Targets, and all mapped EAS Codes.
The LS returns a complete list of Controllers configured in the system.
Format
http://<hostname>/loc/eas/DeleteController
Request
The root element is Controller. The element must specify the "id" attribute. The element must not have any
child elements.
Request Example - EC with OOBB and Multicast
POST /loc/eas/DeleteController HTTP/1.1
Content-Type: application/xml
Content-Length: 90
Location Services API Programming Reference Guide
PN OL-30024-03
39
Application Programming Interface for the Videoscape Location Service
EAS Location Service Interfaces
<ns2:Controller
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
id="EC3">
</ns2:Controller>
The following is a list request responses:
• 204 - No Content
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error
No XML data is included in the response. On a successful response (204 No Content), the response only
consists of the HTTP header. If the specified Controller is not found, the Location Service returns a 404 Not
Found response.
For all other errors, the Location Service returns an appropriate HTTP status code.
Set EAS Alert Target Map
The Set EAS Alert Target Map method is used by the UI to configure the EAS Alert Target to EAS Code
mapping. The UI must specify a full list of EAS Codes for a given OOBB or Multicast. This request directs
the Location Service to discard the previous mapping data and replace it with the new alert code mapping
information. Thus, the Set command can be used to create an initial mapping, update a previous mapping (by
replacing all of the previous entries), or delete all mapping information (by specifying an empty list of mapping
data).
The UI must specify the Controller and either the OOBB or Multicast that is being updated. The LS rejects
any request that has insufficient parameters. The LS will also reject any request if the specified Controller
and OOBB/Multicast combination cannot be found.
Format
http://<hostname>/loc/eas/EASAlertTargetMap
Request
The root element is EASAlertTargetMap. The EASAlertTargetMap element and the EASCode element are
defined in the Get EAS Alert Target Map section of this guide. The Controller, OOBB, and Multicast elements
are defined in the Get EAS Alert Targets section of this guide. Note that no child elements of the Controller
element are specified.
POST /loc/zone/Provider HTTP/1.1
Content-Type: application/xml
Content-Length: 340
<ns2:EASAlertTargetMap
xmlns:ns2="urn:com:cisco:videoscape:conductor:loc">
<Controller id="EC3"/>
<OOBB id="14"/>
<EASCode countryCode="CA" dataType="SGC">1002010</EASCode>
<EASCode countryCode="CA" dataType="SGC">1107001</EASCode>
<EASCode countryCode="CA" dataType="SGC">1107003</EASCode>
</ns2:EASAlertTargetMap>
Request Response - Codes
The following is a list request responses:
• 204 - No Content
• 400 - Bad Request
Location Services API Programming Reference Guide
40
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
• 404 - Not Found
• 500 - Internal Server Error
No XML data is included in the response. On a successful response (204 No Content), the response only
consists of the HTTP header.
The Location Service returns a 404 Not Found if a match cannot be found for the specified alert target (OOBB
or Multicast) associated with the specified Controller.
For all other errors, the Location Service returns an appropriate HTTP status code.
Geographic Region Interface
The geography of a country is typically segmented into distinct sub-divisions for applications such as mail
delivery, census counting, and emergency alert notification, to name a few.
These geographic regions are arranged hierarchically and organized from largest to smallest. Within the United
States, the order is State, County (or equivalent), and then Postal Code. Within Canada, the order is Region,
Province, Census Division, and Census Subdivision.
The Geographic Region Interface provides methods for querying information about this regional hierarchy.
GET Region Data
Request Direction: LS Client to LS
Method: HTTP GET
This method provides a drill-down view into the regional hierarchy. Responses include a listing of the regional
divisions within the specified level and an optional list of data items about that geographic area. The Country
Code for target region is required and omitting other parameter returns the top-level divisions within the
county: States for the United States and Regions for Canada. The regions returned in this query have an "id"
that uniquely identifies it and a descriptive "name". The "id" values returned in elements from an initial request
are used in subsequent queries to further drill down into the given region. The "name" values are for displaying
to users who are making the selections.
In Canada the id and names are in accordance with the Standard Geographical Classification (SGC) as defined
by the government. Details of this classification system are available here:
http://www.statcan.gc.ca/subjects-sujets/standard-norme/sgc-cgt/2011/sgc-cgt-intro-eng.htm. The source data
for Canadian regions is the "Postal Code Conversion File (PCCF)" provided by © Statistics Canada, 2011
(Catalogue no. 92-153-G). This is the same files used for SGC queries by Postal Code.
The ZIP*Data™ database used for the United States follows "FIPS PUB 6-4: COUNTIES AND EQUIVALENT
ENTITIES OF THE UNITED STATES, ITS POSSESSIONS, AND ASSOCIATED AREAS" * in defining
ids & names for states and counties. Zip Codes are always numerical and just include the same data in id &
name. Details for FIPS Pub 6-4 are found here: http://www.itl.nist.gov/fipspubs/fip6-4.htm
*
County equivalents include Alaska census areas, independent cities, Louisiana Parishes and Washington
D.C.
In addition to a regional hierarchy list, queries can optionally request statistical or census information about
the given region. The types of data available and level of granularity vary by country and currently the United
States and Canada are supported.
United States
Location Services API Programming Reference Guide
PN OL-30024-03
41
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
Statistical data for the United States regions is segmented down to the county level. The data fields available
for individual counties include:
• FIPS Code: Used for EAS Alerts.
• Population: Estimated county population.
• Persons Per Household: Average number of persons per household.
• Area: County area in square miles.
• Households: Number of households in the county.
• White: Estimate of White population in county.
• Black: Estimate of Black population in county.
• Hispanic: Estimate of Hispanic population in county.
• Avg Income: Average annual household income.
• Avg House Value: Average value of a home within the county.
United States Counties are sub-divided into Postal/Zip Codes (though these can span county lines) for which
population data is also available. This means the populations for individual zip codes can be queried and the
results of a query for a county's population include the populations for all the zip codes in that county, as well.
All other data fields are only available for county-based queries.
Canada
Statistical data for Canadian regions is segmented down to the Census Subdivision level. At this time the
PCCF file only provides data for SCS Codes used in EAS Alerts. Statistics Canada does provide a free product
(GeoSuite, 2011 Census. Statistics Canada Catalogue no. 92-150-X) that can generate statistical and census
reports for Canadian regions.
Data items can be requested in queries for any of the regional hierarchy and results include values for all lower
nodes in the tree. For example, an EAS query for at the Provence level of the Canadian hierarchy returns the
SGC codes for all Census Subdivisions in that province. There are no functions to aggregate or filter data at
this time, so the client must perform all data manipulation and analysis.
Format
http://<hostname:port>/loc/regions/RegionData?<name>=<value>&...
Request
The following table provides a list of query parameters:
Query
Parameters
Type
R/O Description
CountryCode
String
R
Two character country code based on ISO 3166. Valid values are: US and
CA
RegionId
String
O
Unique identifier for a region in the geographic hierarchy. If omitted the
top-level regions for the country are returned.
Location Services API Programming Reference Guide
42
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
Query
Parameters
Type
R/O Description
Data Type
String
O
Optional list of 0 or more enumerated values indicating the type of data
returned in the query. Valid values and their associated data include:
• EAS: Emergency Alert Codes - US/FIPS | CA/SGC.
• POP: Population estimate based on most recent census data.
• PPH: Average persons per household.
• HHS: Number of households.
• AREA: In square miles.
• WHITE: White population.
• BLACK: Black population.
• HISP: Hispanic population.
• AVGI: Average income.
• AVGV: Average household value.
Request Example - Get sub-regions (postal codes) for Bucks county (42017) Pennsylvania (42):
http://<hostname:port>/loc/regions/RegionData?CountryCode=US&RegionId=42017
Request Example - Get sub-regions (census division) EAS (SGC) codes for Province (3) of Ontario (35):
http://<hostname:port>/loc/regions/RegionData?CountryCode=CA&RegionId=35&DataType=EAS
Request Response - Codes
The following is a list request responses:
• 200 - OK
• 400 - Bad Request
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error
On a successful response, the Location Service returns XML data with a list of regions in the next level of
the hierarchy and optionally a list of data elements associated with the region. The root element is RegionData
as follows.
The Location Service returns 400 Bad Request if the country code is missing or invalid. The Location Service
also returns of 400 Bad Request on an invalid DataType parameter.
The Location Service returns 403 Forbidden if the LS Client does not have privileges to access the provider
name list.
The Location Service returns a 404 Not Found if there is no region matching the criteria. If no data is available
for a given DataType parameter, the query succeeds and an empty DataList element is included.
For all other errors, the Location Service returns an appropriate HTTP status code.
Location Services API Programming Reference Guide
PN OL-30024-03
43
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
Element: RegionData
Children: RegionItems (0..1)
DataList (0..N)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
countryCode String
R/O
Description
R
A Country Code for the response data. Values include: US and CA.
Element: RegionItems
Children: Region (1..N)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
regionId
String
R
A unique identifier for the container region.
regionName String
R
A descriptive name for the container region.
Element: DataList
Children: DataItem (1..N)
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
regionId
String
R
A unique identifier for the container region.
regionName String
R
A descriptive name for the container region.
dataType
R
An enumerated type for values in the DateItem elements.
String
Element: Region
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
Id
String
R
A unique identifier for the container region. This value is used in queries
for data in the next level in the hierarchy.
Type
R/O
Description
String
R
A descriptive name for the region. If not available, this should be the same as the Id.
If populating a user interface, this is the value displayed to the user while the id is
attribute is in backing data.
Location Services API Programming Reference Guide
44
PN OL-30024-03
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
Element: DataItem
Children: None
The following table provides a list of attributes that are associated with this element.
Attribute
Type
R/O
Description
regionId
String
R
The identifier for the region this data is for.
regionName String
R
A descriptive name for the region.
Type
R/O
Description
String
R
The value of a single data item for a specific region. This is returned as a string and
it is upon the client to translate to the necessary format for further processing.
Response Example - Get sub-regions (postal codes) for Bucks county (42017) Pennsylvania (42):
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 325
<RegionData countryCode="US"
xmlns="urn:com:cisco:videoscape:conductor:loc">
<RegionItems regionId=”42017” regionName=”Bucks”>
<Region id=”1890142017”>18901</Region>
<Region id=”1890342017”>18903</Region>
…
</RegionItems>
</RegionData>
Response Example - Get sub-regions (census division) EAS (SGC) codes for Province (3) of Ontario
(35):
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1450
<RegionData countryCode="CA"
xmlns="urn:com:cisco:videoscape:conductor:loc">
<RegionItems regionId=”35” regionName=”Ontario”>
<Region id=”3501” > Stormont, Dundas and Glengarry</Region>
<Region id=”3502” > Prescott and Russell</Region>
…
</RegionItems>
<DataList regionId=”35” regionName=”Ontario” regionDataType=”EAS”>
<DataItem regionId=”3501005” regionName=” South Glengarry” >3501005</DataItem>
<DataItem regionId=”3501007” regionName=” Akwesasne (Part) 59” >3501007</DataItem>
<DataItem regionId=”3502001” regionName=”East Hawkesbury” > 3502001</DataItem>
…
</DataList>
</RegionDataList>
Location Services API Programming Reference Guide
PN OL-30024-03
45
Application Programming Interface for the Videoscape Location Service
Geographic Region Interface
Location Services API Programming Reference Guide
46
PN OL-30024-03
APPENDIX
A
Zone Import File Format Example
• Zone Import File Format Example, page 47
Zone Import File Format Example
Example Import File:
<ZoneDefinitions
xmlns="urn:com:cisco:videoscape:conductor:loc">
<ProviderNameList>
<Provider>cisco</Provider>
<Provider>provider2</Provider>
</ProviderNameList>
<ZoneGroupList>
<ZoneGroup
name="ad_zone_3"
provider="cisco">
<Classifier type="regex">
/http:\/\/cdn\.cisco\.com.*/
</Classifier>
<Zone name="region1">
<MetroCode>504</MetroCode>
<MetroCode>512</MetroCode>
<MetroCode>511</MetroCode>
<PostalCode>19101</PostalCode>
<PostalCode>18936</PostalCode>
</Zone>
<Zone name="region2">
<CountryCode>CA</CountryCode>
</Zone>
<Zone name="region3">
<State>NY</State>
<State>MA</State>
<MetroCode>506</MetroCode>
</Zone>
</ZoneGroup>
<ZoneGroup
name="asn_zone"
provider="provider2">
<Classifier type="simple">images.provider2.com</Classifier>
<Classifier type="simple">cdn.provider2.com</Classifier>
<Zone name="company1">
<ASN>109</ASN>
<ASN>3943</ASN>
<ASN>16417</ASN>
</Zone>
<Zone name="company2">
<ASN>15169</ASN>
<ASN>16591</ASN>
Location Services API Programming Reference Guide
PN OL-30024-03
47
Zone Import File Format Example
Zone Import File Format Example
<ASN>19448</ASN>
<ASN>22577</ASN>
</Zone>
</ZoneGroup>
</ZoneGroupList>
</ZoneDefinitions>
Location Services API Programming Reference Guide
48
PN OL-30024-03