Add / Edit Coverage API
Purpose
The Coverage API allows you to create or edit individual coverages using the API. If you provide a Coverage ID, it will only change the values of the existing coverage.
Fields
Account / API Key
You can locate your Account ID and API Key in the API's Tab of your account settings. Your Account ID can also be found within the iframe of your Multi Coverage.Coverage ID
The Coverage ID field is not a required field unless you are wanting to update an existing coverage on your account. The Coverage ID can be located in the URL when you open any individual Coverage.Coverage Name
The Coverage name field is required and can contain text, numbers dashes and underscore but cannot have return characters or special characters.Tower Site ID
This field is not required but if you do not provide a Site ID, one will be created using the Latitude, Longitude, Coverage Name and Antenna Height. If you wish to assign multiple sectors to a single tower site you will need to use the Get Site List API otherwise you will have several tower locations that are in the same location.Latitude / Longitude
These fields are in decimal degrees. If you are in the northern hemisphere, the value will be positive and negative if you are located in the southern hemisphere for the Latitude. The Longitude will be positive value if you are in the eastern hemisphere and negative for the western hemisphere. Do not enter these values if you use the Site ID from your tower location.Antenna Height
The Height value is numerical values only. It can have decimal values as well. All heights are in meters.Client Average Antenna Height / Client Antenna Gain
The client antenna height is in meters and we suggest you use the average install height of your customer locations for this value.The Client Antenna Gain is a whole number only field. The largest antenna that you perform installs with is suggested for this field.
Rx / Tx Line Loss
This field can be decimal values. For most situations, 0.5 is enough line loss unless your equipment is installed with significant amount of cable between the radio and the antenna. If this is the case, you will need to use the specifications of the cable to determine how much loss you have on your cable.Antenna Type
There are many antenna pattern files in TowerCoverage.com. You also have the ability to upload you own pattern files in Radio Mobile Compatible .ant format in your account settings. You will need to use the value assigned to the antenna that you wish to use by requesting the list from the Get Antenna Type API.Antenna Azimuth
The Azimuth field is a required field and only whole numbers between 0 and 360 are allowed. There is no need to enter the special character for degrees. This should be set to the magnetic degrees that your sector is facing. Any value is acceptable for an omni directional antenna.Beam Width Filter
The Beam Width Filter is a required field and only whole numbers between 0 and 360 are allowed. This has no effect on the propagation of the coverage. It tells the incoming EUS Data as well as the Path Analysis feature the angle in which to allow submissions. In most cases, sectors have a slight wider beam than that of the advertised width. It is good practice to add 10 to the advertised beam width (Example: 90 degree sector would have a Beam Width of 100
. )
Antenna Tilt
The antenna tilt field is a required. This allows you to set the mechanical tilt of the antenna. Values must be a whole number using positive numbers for up-tilt and negative numbers for down-tilt. If you are using the correct pattern file for your coverage, the electrical tilt is already built into the coverage.Antenna Gain
The antenna gain field is a required. Values must be whole numbers only with no text added. Although the Gain is listed in the antenna pattern, you will still need to input the appropriate gain of the antenna that you are using.Frequency / Exact Center Frequency
The Frequency setting values are obtained by using the Get Frequency List and is required for the request. These values change periodically due to more frequencies being added to the available list. The Exact Center Frequency is not required but can be added as a whole number value and will allow you to use the Frequency Coordination feature on the Multi Maps of your account.Tx Power
For the Tx Power Setting of your coverage, you will need to use whole number values in dBm. If your radio settings are in Watts or Milli-watts, you will need to convert them before inputting them to prevent inaccuracies in your coverage.Rx Threshold
This is the minimum Rx value that you wish to show on your coverage map and is whole number only value. For WISP operations, we recommend this to be within a few dB of your company’s minimum installation requirements. This will limit the coverage map to only show locations at this value or above. Any location that would get less that this value will not show on your coverage map (even as little as 0.1 dBm less). Our standard recommendation is a -65, but what you enter in this field is based on what values your company’s policies will allow installations. A higher Rx Threshold will reduce your coverage area and will not include areas that lower signal is available at with reduced signal margins. Example: If your company’s standard is that no customer will be installed below -70. Then -70 is your Rx Threshold value. You will need to assume that there is some signal margin in there as well. If your radio’s manufacturer Rx Sensitivity is -78, setting a -70 in this value would allow for an 8db margin.
Strong/Weak Signal Colors
These values are required. You can select a color hex code to enter here to set the Coverage Colors or you can use the same as the Coverage Creation inside your TowerCoverage.com Account. (Green) Strong Color: 00FF00 (Red) Weak Color: FF0000Channel Width
This field is not required. The Channel width value on a Coverage is used when the sector is an LTE Coverage so that the RSRP Value can be displayed. The appropriate value for using this field can be obtained by using the GetChannelWidthAPI.Land Cover Type
This field is not required but you can retrieve the list of Land Cover Type ID from your account by using the GetLandCoverList. This will provide all the ID's and names of the Land Cover Types on your account. If you do not provide a Land Cover Type ID, the system will use the same values that you seen when you first created the TowerCoverage.com account.Use Land Cover / Use Two Rays / Data Image / Create Viewshed/ LTE
All four of these fields have a valid value of 1 for yes or 0 for no.Use Land Cover
This tells the site whether or not to take you Land Cover settings into account in the calculations. See also Land Cover for more information.
Use Two Rays
Two rays are used for multi-path calculations. Most WISP use radios that cannot do multi-path reflections so by default this option is turned off. If your radio system can use multi-path reflections then you may want to turn this value on.
Data Image
DataImage is a required field and must be represented as either a 1 or 0. When active it provides access to Map Data Overlays in the form of a Population Density or LandCover. A value of 1 will make this option active.
Create Viewshed
The view shed options, sets all land cover density values to 10000, or their maximum value. This means that as soon as a signal attempts to go through any type of land cover, it will result in a loss so great that the signal will not travel through it. This creates a view shed; but unlike other systems, the views held do take into account land cover values, such as tree heights etc. If you are using radio systems in frequencies in 5 GHz or larger, in most cases, trees will attenuate the signal to an unusable level. Some customers wish to not see any locations that trees would have an impact on service, so the view shed option is what they would wish to use.
For WISP operations, we recommend that any frequencies above 2.4 GHz should use the view shed option, as those frequencies at the power levels we use, will stop the transmitted signals. 2.4 GHz and under though does have decent foliage penetration, so leaving the view shed off for these frequencies is recommended.
LTE
The LTE Field is a 1 or 0 for yes or no value to label if this is an LTE Coverage or not. Coverages that are labeled as LTE will display the RSRP Value for Path Analysis and End User Submissions.
Code Examples
SOAP 1.1
Request
POST /towercoverage.asmx HTTP/1.1 Host: api.towercoverage.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://tempuri.org/CoverageAPI" <?xml version="1.0" encoding="utf-8" ?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <CoverageAPI xmlns="http://tempuri.org/"> <Account>string</Account> <Coverageid>string</Coverageid> <Coveragename>string</Coveragename> <TowerSiteid>string</TowerSiteid> <Latitude>string</Latitude> <Longitude>string</Longitude> <AntennaHeight>string</AntennaHeight> <ClientAverageAntennaHeight>string</ClientAverageAntennaHeight> <ClientAntennaGain>string</ClientAntennaGain> <RxLineLoss>string</RxLineLoss> <AntennaType>string</AntennaType> <AntennaAzimuth>string</AntennaAzimuth> <BeamwidthFilter>string</BeamwidthFilter> <AntennaTilt>string</AntennaTilt> <AntennaGain>string</AntennaGain> <Frequency>string</Frequency> <ExactCenterFrequency>string</ExactCenterFrequency> <TXPower>string</TXPower> <TxLineLoss>string</TxLineLoss> <RxThreshold>string</RxThreshold> <RequiredReliability>string</RequiredReliability> <StrongSignalMargin>string</StrongSignalMargin> <StrongSignalColor>string</StrongSignalColor> <WeakSignalColor>string</WeakSignalColor> <Opacity>string</Opacity> <MaximumRange>string</MaximumRange> <RenderingQuality>string</RenderingQuality> <UseLandCover>string</UseLandCover> <LandCover>string</LandCover> <UseTwoRays>string</UseTwoRays> <IsLTE>string</IsLTE> <ChannelID>string</ChannelID> <CreateViewshed>string</CreateViewshed> <key>string</key> </CoverageAPI> </soap:Body> </soap:Envelope>
Response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8" ?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <CoverageAPIResponse xmlns="http://tempuri.org/"> <CoverageAPIResult>string</CoverageAPIResult> </CoverageAPIResponse> </soap:Body> </soap:Envelope>
SOAP 1.2
Request
POST /towercoverage.asmx HTTP/1.1 Host: api.towercoverage.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8" ?> <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:Body> <CoverageAPI xmlns="http://tempuri.org/"> <Account>string</Account> <Coverageid>string</Coverageid> <Coveragename>string</Coveragename> <TowerSiteid>string</TowerSiteid> <Latitude>string</Latitude> <Longitude>string</Longitude> <AntennaHeight>string</AntennaHeight> <ClientAverageAntennaHeight>string</ClientAverageAntennaHeight> <ClientAntennaGain>string</ClientAntennaGain> <RxLineLoss>string</RxLineLoss> <AntennaType>string</AntennaType> <AntennaAzimuth>string</AntennaAzimuth> <BeamwidthFilter>string</BeamwidthFilter> <AntennaTilt>string</AntennaTilt> <AntennaGain>string</AntennaGain> <Frequency>string</Frequency> <ExactCenterFrequency>string</ExactCenterFrequency> <TXPower>string</TXPower> <TxLineLoss>string</TxLineLoss> <RxThreshold>string</RxThreshold> <RequiredReliability>string</RequiredReliability> <StrongSignalMargin>string</StrongSignalMargin> <StrongSignalColor>string</StrongSignalColor> <WeakSignalColor>string</WeakSignalColor> <Opacity>string</Opacity> <MaximumRange>string</MaximumRange> <RenderingQuality>string</RenderingQuality> <UseLandCover>string</UseLandCover> <LandCover>string</LandCover> <UseTwoRays>string</UseTwoRays> <IsLTE>string</IsLTE> <ChannelID>string</ChannelID> <CreateViewshed>string</CreateViewshed> <key>string</key> </CoverageAPI> </soap12:Body> </soap12:Envelope>
Response
HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8" ?> <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:Body> <CoverageAPIResponse xmlns="http://tempuri.org/"> <CoverageAPIResult>string</CoverageAPIResult> </CoverageAPIResponse> </soap12:Body> </soap12:Envelope>
HTTP Get
Request
GET /towercoverage.asmx/CoverageAPI? Account=string& Coverageid=string& Coveragename=string& TowerSiteid=string& Latitude=string& Longitude=string& AntennaHeight=string& ClientAverageAntennaHeight=string& ClientAntennaGain=string& RxLineLoss=string& AntennaType=string& AntennaAzimuth=string& BeamwidthFilter=string& AntennaTilt=string& AntennaGain=string& Frequency=string& ExactCenterFrequency=string& TXPower=string& TxLineLoss=string& RxThreshold=string& RequiredReliability=string& StrongSignalMargin=string& StrongSignalColor=string& WeakSignalColor=string& Opacity=string& MaximumRange=string& RenderingQuality=string& UseLandCover=string& LandCover=string& UseTwoRays=string& IsLTE=string& ChannelID=string& CreateViewshed=string& key=string HTTP/1.1 Host: api.towercoverage.com
Response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8" ?> <string xmlns="http://tempuri.org/">string</string>
HTTP Post
Request
POST /towercoverage.asmx/CoverageAPI HTTP/1.1 Host: api.towercoverage.com Content-Type: application/x-www-form-urlencoded Content-Length: length Account=string& Coverageid=string& Coveragename=string& TowerSiteid=string& Latitude=string& Longitude=string& AntennaHeight=string& ClientAverageAntennaHeight=string& ClientAntennaGain=string& RxLineLoss=string& AntennaType=string& AntennaAzimuth=string& BeamwidthFilter=string& AntennaTilt=string& AntennaGain=string& Frequency=string& ExactCenterFrequency=string& TXPower=string& TxLineLoss=string& RxThreshold=string& RequiredReliability=string& StrongSignalMargin=string& StrongSignalColor=string& WeakSignalColor=string& Opacity=string& MaximumRange=string& RenderingQuality=string& UseLandCover=string& LandCover=string& UseTwoRays=string& IsLTE=string& ChannelID=string& CreateViewshed=string& key=string
Response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8" ?> <string xmlns="http://tempuri.org/">string</string>