Reference Guide#
Introduction#
For both the U.S. and Canada, Web Smart ZIP Search Service will:
Finds cities tied to a given ZIP or Postal code.
Retrieves ZIP or Postal Codes associated with a given city and state/province.
Find city names that match a specific pattern within a given state or province.
The ZIP Search service has three different types of searches.
Service URLs#
Protocol |
URL |
|---|---|
SOAP |
|
SOAP:WSDL |
|
SOAP:Flat WSDL |
|
XML |
|
REST |
Sample Code#
Zip Search Types#
Find Cities in ZIP Code#
This search returns all of the matching city name records associated with a submitted ZIP/Postal Code. This may include unincorporated communities adjoining a city and alternative names and spellings for a given city.
If the OfficialCityNamesOnly option is enabled, this search will only return the record that matches the official USPS city name associated with the ZIP Code.
Find ZIP In Cities Search#
This search returns all of the ZIP/Postal code records associated with a submitted combination of city name and state.
Find Cities in State Search#
This search returns all of city names that match a submitted city name pattern and state/province.
The city name can employ a wildcard character.
For example, the search strings Rancho S* and CA will return records for all cities in California that begin with the letters Rancho S.
Adding ZIP Search to a Project#
If you are using the SOAP service with Visual Studio .NET, you need to add a web reference to the service to your project.
Click on the Project menu and select Add Web Reference....
Enter the following URL on the Add Web Reference dialog box:
https://zipsearch.melissadata.net/v2/SOAP/Service.svc
If you are not using Visual Studio .NET, see the documentation for your SOAP interface for the procedure for adding the service to your project.
Submitting an XML Request#
After building your XML string from your data, an XML request to the web service is submitted using an HTTP POST operation to the following URL:
https://zipsearch.melissadata.net/v2/XML/Service.svc/doZipSearch
Building a REST Request#
Query strings are sent to the web service as part of the URL using an HTTP Get operation appended to following URL:
https://zipsearch.melissadata.net/v2/REST/Service.svc/doZipSearch
ZIP Search Request#
At the minimum, a request to the WebSmart ZIP Search Service will consist of either a ZIP/Postal Code or a City and State combination, depending on the type of search selected. Only one record is allowed per request.
SOAP Request#
The following Visual Basic Code shows a simple order of operations for building and submitting a Request object, submitting it to the Web Service and retrieving a response object.
Step 1 – Create the Request and Response Objects
Dim ReqZipSearch As New dqwsZipSearch.Request
Dim ResZipSearch As New dqwsZipSearch.Response
Step 2 – Assign the General Request Values
There are three properties of the Request object that apply to the request as a whole. CustomerID is required.
ReqZipSearch.CustomerID = strCustID
ReqZipSearch.TransmissionReference = strTranRef
ReqZipSearch.SearchType = "1"
ReqZipSearch.OptOfficialCityNameOnly = True
The Transmission Reference is a unique string value that identifies this request.
The OptOfficialCityNameOnly option applies only to Search Type 1 (Cities in ZIP Code).
Step 3 – Build the Record
The exact method for building the array will depend on the exact database software in use, but you will need to assign the required values to the corresponding elements in the Request.
Find Cities In ZIP Code
ReqZipSearch.Zip = "92688"Find ZIP Codes in City
ReqZipSearch.City = "Rancho Santa Margarita" ReqZipSearch.State = "CA"Find Cities in State
ReqZipSearch.City = "Rancho S*" ReqZipSearch.State = "CA"
Step 4 – Submit the Request
The final step is to create the Service Client Object and then submit the Request object doZipSearch method. This sends the data to the web service and retrieves the Response object.
ZipSearchClient = New dqwsZipSearch.Service
ResZipSearch = ZipSearchClient.doZipSearch(ReqZipSearch)
XML Request#
The raw XML request is built using whatever XML tools are available via your development tools and submitted to the following URL using an HTTP POST request:
https://zipsearch.melissadata.net/v2/XML/Service.svc/doZipSearch
The following XML Code contains the same request as the SOAP example above.
Find Cities in ZIP Code
<?xml version="1.0" ?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test</TransmissionReference>
<CustomerID xmlns="urn:mdWebServiceZipSearch">XXXXXXXX</CustomerID>
<SearchType xmlns="urn:mdWebServiceZipSearch">1</SearchType>
<OptOfficialCityNameOnly xmlns="urn:mdWebServiceZipSearch">false</OptOfficialCityNameOnly>
<City xmlns="urn:mdWebServiceZipSearch">Rancho Santa Margarita</City>
<State xmlns="urn:mdWebServiceZipSearch">CA</State>
<Zip xmlns="urn:mdWebServiceZipSearch">92688</Zip>
<Country xmlns="urn:mdWebServiceZipSearch" />
</Request>
Find ZIP Codes in City
<?xml version="1.0" ?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test</TransmissionReference>
<CustomerID xmlns="urn:mdWebServiceZipSearch">XXXXXXXX</CustomerID>
<SearchType xmlns="urn:mdWebServiceZipSearch">2</SearchType>
<OptOfficialCityNameOnly xmlns="urn:mdWebServiceZipSearch">false</OptOfficialCityNameOnly>
<City xmlns="urn:mdWebServiceZipSearch">Rancho Santa Margarita</City>
<State xmlns="urn:mdWebServiceZipSearch">CA</State>
<Zip xmlns="urn:mdWebServiceZipSearch">92688</Zip>
<Country xmlns="urn:mdWebServiceZipSearch" />
</Request>
Find Cities in State
<?xml version="1.0" ?>
<Request xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test</TransmissionReference>
<CustomerID xmlns="urn:mdWebServiceZipSearch">XXXXXXXX</CustomerID>
<SearchType xmlns="urn:mdWebServiceZipSearch">3</SearchType>
<OptOfficialCityNameOnly xmlns="urn:mdWebServiceZipSearch">false</OptOfficialCityNameOnly>
<City xmlns="urn:mdWebServiceZipSearch">Rancho Santa Margarita</City>
<State xmlns="urn:mdWebServiceZipSearch">CA</State>
<Zip xmlns="urn:mdWebServiceZipSearch">92688</Zip>
<Country xmlns="urn:mdWebServiceZipSearch" />
</Request>
REST Request#
A REST request can submit a single address record via an HTTP GET. The following example uses the same address as the SOAP and XML samples.
Find Cities in ZIP Code
https://zipsearch.melissadata.net/v2/REST/Service.svc/doZipSearch?id=12345678&opt=true&stype=1&zip=92688
Find ZIP Codes in City
https://zipsearch.melissadata.net/v2/REST/Service.svc/doZipSearch?id=12345678&stype=2&city=Rancho%20Santa%20Margarita&state=CA
Find Cities in State
https://zipsearch.melissadata.net/v2/REST/Service.svc/doZipSearch?id=12345678&stype=3&city=Rancho%20S%2A&state=CA
Request Elements#
The following section lists the elements that set the basic options for each and identify the user to the Web Service.
Customer ID#
This is a required string value containing the identifier number issued to the customer when signing up for Melissa Data Web Services.
You need a customer ID to access any Melissa Data Web Service. If this element is not populated, the web service will return an error. To receive a customer ID, call your Melissa Data sale representative.
SOAP#
Request.CustomerID = string
XML#
<Request>
<CustomerID>String</CustomerID>
</Request>
REST#
id={CustomerID}
Transmission Reference#
This is an optional string value that may be passed with each Request to serve as a unique identifier for this set of records.
This value is returned as sent by the Response Array, allowing you to match the Response to the Request.
SOAP#
Request.TransmissionReference = string
XML#
<Request>
<TransmissionReference>String</TransmissionReference>
</Request>
REST#
t={transmissionReference}
SearchType#
This element selects which search method the ZIP Search web service will use with the current request.
The valid values are:
Parameter |
Description |
|---|---|
|
Default. Find Cities in ZIP Code. |
|
Find ZIP Codes in City. |
|
Find City Names in State. |
Any values not matching one of these values will be ignored and the default value of 1 will be used.
SOAP#
Request.SearchType = string
XML#
<Request>
<SearchType>String</SearchType>
</Request>
REST#
stype={SearchType}
OptOfficialCityNameOnly#
This Boolean value instructs the web service to return all cities associated with a ZIP/Postal Code during a Find Cities in ZIP Code Search or to return just the official city.
This value will be ignored during a Find ZIP Codes in City Search and Find City Names in State Search.
Parameter |
Description |
|---|---|
|
Default. Will return all cities found in the input ZIP/Postal code. |
|
Will only return one search record, the official city. |
If a invalid value is entered or this element is omitted altogether, the Default value of False will be used.
SOAP#
Request.OptOfficialCityNameOnly = string
XML#
<Request>
<OptOfficialCityNameOnly>String</OptOfficialCityNameOnly>
</Request>
REST#
opt={OptOfficialCityNameOnly}
City#
This element passes the city name to the ZIP Search service for the ZIP/Postal Codes in City and Cities in State Search Types.
The City Element is required for both the ZIP/Postal Codes in City and Cities in State Search Types.
For the cities in State search, the City element can contain a trailing wildcard character, *, for multiple matches.
Note that the asterisk character must be encoded (%2A) when using with the REST interface.
SOAP#
Request.City = string
XML#
<Request>
<City>String</City>
</Request>
REST#
city={City}
State#
This element passes the state abbreviation to the ZIP Search service for the ZIP/Postal Codes in City and Cities in State.
The State Element is required for both the ZIP/Postal Codes in City and Cities in State Search Types.
SOAP#
Request.State = string
XML#
<Request>
<State>String</State>
</Request>
REST#
state={State}
Zip#
This element passes a five-digit ZIP Code or a six-digit Postal Code to the ZIP Search service for the Cities in ZIP Code Search Type.
The ZIP element is required for the Cities in ZIP Code Search Type.
SOAP#
Request.Zip = string
XML#
<Request>
<Zip>String</Zip>
</Request>
REST#
zip={Zip}
Country#
This element passes a two-character country code to the ZIP Search service.
Currently, ZIP Search only works on addresses within the United States and Canada, so this element is optional and has no effect. It is included for future compatibility.
SOAP#
Request.Country = string
XML#
<Request>
<Country>String</Country>
</Request>
REST#
ctry={Country}
Zip Search Response#
The SOAP interface for the Zip Search service returns a Response Object.
The primary component of this object is a record array of ZIP/Postal Code and City information, one for each ZIP record returned.
The XML and REST interfaces return XML documents containing a number of <ZipRecord> elements, one for each zip record returned.
TransmissionReference#
Returns a string value containing the contents of the TransmissionReference element from the original Request.
If you passed any value to the TransmissionReference element when building your request, it is returned here. You can use this property to match the response to the request.
SOAP#
string = Response.TransmissionReference
XML and REST#
<ResponseArray>
<TransmissionReference>String</TransmissionReference>
</ResponseArray>
Total Records#
Returns a string value containing the number of ZIP/Postal Code or City records returned with the current response.
This property returns the number of ZipSearch Records processed and returned by the response as a string value.
SOAP#
string = Response.TotalRecords
XML and REST#
<ResponseArray>
<TotalRecords>String</TotalRecords>
</ResponseArray>
Results#
Returns a string value containing the general error, system error, and search error messages from the most recent request sent to the service.
For a list of these codes, see ZipSearch - Result Codes.
SOAP#
string = Response.Results
XML and REST#
<ResponseArray>
<Results>String</Results>
</ResponseArray>
Version#
Returns a string value containing the current version number of the Zip Search service.
SOAP#
string = Response.Version
XML and REST#
<ResponseArray>
<Version>String</Version>
</ResponseArray>
ZipRecord Elements#
The SOAP version of the Response object returns a property called ZipRecord which is an array of ZipRecord objects matching the input submitted with the Request with the original.
The XML and REST services may return one or more <ZipRecord> elements that match the original request.
The maximum number of records returned in both cases in 1,000.
The following section describes the elements returned by each record in the Response Object.
Record ID#
For each record in the Response, this element returns a string value containing the sequential identifier for the current ZipRecord.
The RecordID is sequential number to aid in organizing the ZipRecords returned by the Zip Search service.
SOAP#
string = Response.ZipRecord().RecordID
XML and REST#
<Response>
<ZipRecord>
<RecordID>String</RecordID>
</ZipRecord>
</Response>
Zip#
This element returns a string value with the zip code for the current ZIP record.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
SOAP#
string = Response.ZipRecord().Zip
XML and REST#
<Response>
<ZipRecord>
<Zip>String</Zip>
</ZipRecord>
</Response>
ZipType#
This element returns a one-character string value with the code for the ZIP Code type for the current ZIP record.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
For a list of these codes, see ZipSearch - Product Codes.
SOAP#
string = Response.ZipRecord().ZipType
XML and REST#
<Response>
<ZipRecord>
<ZipType>String</ZipType>
</ZipRecord>
</Response>
City#
These elements return string values with the city name and city abbreviation for the current ZIP record.
If the return value of the GetCity function is longer than 13 letters, the GetCityAbbreviation function will return the official abbreviation the post office has associated with that city or municipality name.
For example, for Rancho Santa Margarita, the CityAbbreviation function will return the abbreviation Rcho Sta Marg.
If the return value of the GetCity function is 13 letters long or shorter, the GetCityAbbreviation function will return the full city or municipality name.
This element is returned by all three search types.
SOAP#
string = Response.ZipRecord().City.Name
string = Response.ZipRecord().City.Abbreviation
XML and REST#
<Response>
<ZipRecord>
<City>
<Name>String</Name>
<Abbreviation>String</Abbreviation>
</City>
</ZipRecord>
</Response>
County#
These elements return string values with the county name and five-digit county FIPS code of the current ZIP record.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
The FIPS Code is only returned for U.S. records.
SOAP#
string = Response.ZipRecord().County.Name
string = Response.ZipRecord().County.FIPS
XML and REST#
<Response>
<ZipRecord>
<County>
<Name>String</Name>
<FIPS>String</FIPS>
</County>
</ZipRecord>
</Response>
State#
This element returns a string value with the two-letter state abbreviation of the current ZIP record.
This element is returned by all three search types.
SOAP#
string = Response.ZipRecord().State
XML and REST#
<Response>
<ZipRecord>
<State>String</State>
</ZipRecord>
</Response>
Area Code#
This element returns a three-character string value with the area code of the current ZIP record.
If a ZIP/Postal Code has more than one area code assigned to it, the dominant area code will be returned.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
SOAP#
string = Response.ZipRecord().AreaCode
XML and REST#
<Response>
<ZipRecord>
<AreaCode>String</AreaCode>
</ZipRecord>
</Response>
Time Zone#
These elements return string values containing the time zone name and time zone code of the current zip record.
Possible values are:
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
For a list of these codes, see ZipSearch - Product Codes.
SOAP#
string = Response.ZipRecord().TimeZone.Code
string = Response.ZipRecord().TimeZone.Name
XML and REST#
<Response>
<ZipRecord>
<Latitude>
<Code>String</Code>
<Name>String</Name>
</Latitude>
</ZipRecord>
</Response>
Latitude#
This element returns a string value with the latitude of the current ZIP record.
The latitude is a 9 character number accurate to 6 decimal places.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
SOAP#
string = Response.ZipRecord().Latitude
XML and REST#
<Response>
<ZipRecord>
<Latitude>String</Latitude>
</ZipRecord>
</Response>
Longitude#
This element returns a string value with the longitude of the current ZIP record.
The longitude is a 9 character number accurate to 6 decimal places.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
SOAP#
string = Response.ZipRecord().Longitude
XML and REST#
<Response>
<ZipRecord>
<Longitude>String</Longitude>
</ZipRecord>
</Response>
LastLineIndicator#
This element returns a one character string value with the LastLineIndicator of the current ZIP record.
An L in this element indicates that the city name is the official U. S. Postal Service name for the ZIP Code (Only one record per ZIP Code is coded with an L).
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
This property does not return a value for Canadian records.
SOAP#
string = Response.ZipRecord().LastLineIndicator
XML and REST#
<Response>
<ZipRecord>
<LastLineIndicator>String</LastLineIndicator>
</ZipRecord>
</Response>
LastLineNumber#
This element returns a string value with the LastLineNumber of the current ZIP record.
The LastLineNumber is a 6 digit number used to break ties on certain records using city names.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
This property does not return a value for Canadian records.
SOAP#
string = Response.ZipRecord().LastLineNumber
XML and REST#
<Response>
<ZipRecord>
<LastLineNumber>String</LastLineNumber>
</ZipRecord>
</Response>
PreferredLastLineNumber#
This element returns a string value with the Preferred LastLine Number of the current zip record.
The PreferredLastLineNumber property is a 6-character string value containing the preferred last line number for the city name.
This is similar to the LastLineNumber element mentioned earlier.
If the preferred last line number is the same as the last line number, this city name is the one the Post Office will recognize as the official name for that ZIP Code.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
SOAP#
string = Response.ZipRecord().PreferredLastLineNumber
XML and REST#
<Response>
<ZipRecord>
<PreferredLastLineNumber>String</PreferredLastLineNumber>
</ZipRecord>
</Response>
FacilityCode#
This element returns a string value with the facility code of the current ZIP record.
This element returns values for the Find Cities in ZIP Code and Find ZIP Codes in City search types. It returns a blank for Find City Names in State.
This property does not return a value for Canadian records.
For a list of these codes, see ZipSearch - Product Codes.
SOAP#
string = Response.ZipRecord().FacilityCode
XML and REST#
<Response>
<ZipRecord>
<FacilityCode>String</FacilityCode>
</ZipRecord>
</Response>
Response Object XML Format#
The following shows the structure of the XML document returned by the WebSmart ZipSearch Service.
Find City in Zip#
<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Version xmlns="urn:mdWebServiceZipSearch">2.0.22</Version>
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test
</TransmissionReference>
<Results xmlns="urn:mdWebServiceZipSearch">ZS01</Results>
<TotalRecords xmlns="urn:mdWebServiceZipSearch">4</TotalRecords>
<ZipRecord xmlns="urn:mdWebServiceZipSearch">
<RecordID>1</RecordID>
<Zip>92688</Zip>
<ZipType />
<City>
<Name>Rancho Santa Margarita</Name>
<Abbreviation>Rcho Sta Marg</Abbreviation>
</City>
<County>
<Name>Orange</Name>
<FIPS>06059</FIPS>
</County>
<State>CA</State>
<AreaCode>949</AreaCode>
<TimeZone>
<Name>Pacific Time</Name>
<Code>08</Code>
</TimeZone>
<Latitude>33.6370</Latitude>
<Longitude>-117.6042</Longitude>
<LastLineIndicator>L</LastLineIndicator>
<LastLineNumber>Z22621</LastLineNumber>
<PreferredLastLineNumber>Z22621</PreferredLastLineNumber>
<FacilityCode>B</FacilityCode>
</ZipRecord>
...
<ZipRecord xmlns="urn:mdWebServiceZipSearch">
<RecordID>4</RecordID>
<Zip>92688</Zip>
<ZipType />
<City>
<Name>Rsm</Name>
<Abbreviation>Rsm</Abbreviation>
</City>
<County>
<Name>Orange</Name>
<FIPS>06059</FIPS>
</County>
<State>CA</State>
<AreaCode>949</AreaCode>
<TimeZone>
<Name>Pacific Time</Name>
<Code>08</Code>
</TimeZone>
<Latitude>33.6370</Latitude>
<Longitude>-117.6042</Longitude>
<LastLineIndicator />
<LastLineNumber>Z24594</LastLineNumber>
<PreferredLastLineNumber>Z22621</PreferredLastLineNumber>
<FacilityCode>N</FacilityCode>
</ZipRecord>
</ResponseArray>
Find Zip in City#
<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Version xmlns="urn:mdWebServiceZipSearch">2.0.22</Version>
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test
</TransmissionReference>
<Results xmlns="urn:mdWebServiceZipSearch">ZS02</Results>
<TotalRecords xmlns="urn:mdWebServiceZipSearch">1</TotalRecords>
<ZipRecord xmlns="urn:mdWebServiceZipSearch">
<RecordID>1</RecordID>
<Zip>92688</Zip>
<ZipType />
<City>
<Name>Rancho Santa Margarita</Name>
<Abbreviation>Rcho Sta Marg</Abbreviation>
</City>
<County>
<Name>Orange</Name>
<FIPS>06059</FIPS>
</County>
<State>CA</State>
<AreaCode>949</AreaCode>
<TimeZone>
<Name>Pacific Time</Name>
<Code>08</Code>
</TimeZone>
<Latitude>33.6370</Latitude>
<Longitude>-117.6042</Longitude>
<LastLineIndicator>L</LastLineIndicator>
<LastLineNumber>Z22621</LastLineNumber>
<PreferredLastLineNumber>Z22621</PreferredLastLineNumber>
<FacilityCode>B</FacilityCode>
</ZipRecord>
</ResponseArray>
Find City in State#
<?xml version="1.0" ?>
<ResponseArray xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Version xmlns="urn:mdWebServiceZipSearch">2.0.22</Version>
<TransmissionReference xmlns="urn:mdWebServiceZipSearch">Test
</TransmissionReference>
<Results xmlns="urn:mdWebServiceZipSearch">ZS03</Results>
<TotalRecords xmlns="urn:mdWebServiceZipSearch">1</TotalRecords>
<ZipRecord xmlns="urn:mdWebServiceZipSearch">
<RecordID>1</RecordID>
<Zip>00000</Zip>
<ZipType />
<City>
<Name>Rancho Santa Margarita</Name>
<Abbreviation>Rcho Sta Marg</Abbreviation>
</City>
<County>
<Name />
<FIPS />
</County>
<State>CA</State>
<AreaCode />
<TimeZone>
<Name />
<Code />
</TimeZone>
<Latitude>0.0000</Latitude>
<Longitude>0.0000</Longitude>
<LastLineIndicator />
<LastLineNumber />
<PreferredLastLineNumber />
<FacilityCode />
</ZipRecord>
</ResponseArray>