local.com xml feed guidelines jan 12
TRANSCRIPT
LOCAL DISTRIBUTION SERVICES (LDS) API
Version 33 Last Updated Jan 2012
Localcom Local Distribution Service (LDS) API Version | 33
Page | 2
Table of Contents OVERVIEW 4
LDS ACCOUNT SETUP 6
Traditional Method A (Using aff Parameter) 6
New Method B (New Method Using appid Parameter) 6
LDS API FUNDAMENTALS 6
Call Basics 6
The LDS Sandbox 7
INPUT PARAMETERS 7
Required Parameters 7
Optional Parameters 8
CALL SYNTAX 9
EXAMPLES 10
Input using a City and State 10
Input using a ZIP code and Maxresults of 20 11
PARAMETER NOTES 11
Results Sorting Options 11
Sorting Details 11
Distance 12
Filtering by Letter 12
Location in LDS 12
THE ltinfogt SEGMENT 13
The ltparametersgt Subsection 13
The ltlocationgt section 13
The lttypegt Subsection 14
The ltnearbycitiesgt Subsection 14
The ltweathergt Subsection 14
The ltspellinggt Subsection 14
The ltalphabetgt Subsection 15
The ltcategoryStatgt Subsection 15
Localcom Local Distribution Service (LDS) API Version | 33
Page | 3
The lterrorgt Subsection 15
The ltresultsetgt Subsection 15
The ltresultgt Subsection 16
The ltlocalgt Subsection 17
The ltextendedgt Subsection 18
CALLING LDS FOR PROFILE PAGE 19
The ltprofilegt Segment 21
SAMPLE CALLS 22
A Sample Call in C 22
A Sample Call in Java 23
A Sample Call in PHP 23
APPENDICES 25
Appendix A ndash XML Feed Results Example 25
Appendix B ndash Frequently Asked Questions 27
Localcom Local Distribution Service (LDS) API Version | 33
Page | 4
OVERVIEW The Localcom Local Distribution Service (LDS) application programming interface (API)
provides an open standards interface for use by developers at Localcom partner sites
This interface is referred to as the LDS API
The LDS API works with any platform or technology and gives developers full access to an
XML feed of local search results profile pages and advertising for all locations in the
United States Built on Localcom‟s proprietary search technology the LDS API connects
subscribers to a high-speed highly-reliable content-rich source of local business listings
and targeted local advertising
There are two LDS api endpoints Any new user needs to use the v2 api as it has more
features For example Json format is supported only in v2 api We also encourage existing
LDS user to upgrade to v2 api LDS v1 api is provided for backward compatibility purpose
for a period of time and will be dropped out later
LDS api endpoint V2
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
LDS call endpoint V1
httpldslocalcomldssearchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]ampref
errer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
This guide describes the calls in the LDS API and helps you understand the LDS data feed
on your web properties to maximize your revenues on local search traffic The major
sections in this guide are as follows
LDS Account Setup describes what you need to do before using the LDS API
LDS API Fundamentals provides basic information on the LDS API
Input Parameters describe the various required and optional parameters of an LDS
API call
Call Syntax describes the syntax of an LDS API call
Examples show various examples of LDS API input and the resulting XML output
Parameter Notes describe the syntax of an LDS API call
Info Section describes the ltinfogt section that appears within each XML response
This section may contain multiple subsections each of which may contain multiple
fields
o The ltparametersgt subsection
o The ltlocationgt subsection
o The ltspellinggt subsection
o The ltalphabetgt subsection
o The lterrorgt subsection
o The ltcategoryStatgt subsection
Localcom Local Distribution Service (LDS) API Version | 33
Page | 5
o The ltresultsetgt subsection
Calling LDS for Profile Page describes how to access the profile page of a courtesy
listing
Sample Calls provides a sample LDS API call in three different programming
languages C Java and PHP
Appendix A XML Feed Results Example provides an instance of the feed results
Appendix B Frequently Asked Questions answers commonly asked questions
Use this guides table of contents if youre looking for something specific If theres
something you need and can‟t find within this guide send your question to our customer
support at ldssupportlocalcom and well get you what you need
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 2
Table of Contents OVERVIEW 4
LDS ACCOUNT SETUP 6
Traditional Method A (Using aff Parameter) 6
New Method B (New Method Using appid Parameter) 6
LDS API FUNDAMENTALS 6
Call Basics 6
The LDS Sandbox 7
INPUT PARAMETERS 7
Required Parameters 7
Optional Parameters 8
CALL SYNTAX 9
EXAMPLES 10
Input using a City and State 10
Input using a ZIP code and Maxresults of 20 11
PARAMETER NOTES 11
Results Sorting Options 11
Sorting Details 11
Distance 12
Filtering by Letter 12
Location in LDS 12
THE ltinfogt SEGMENT 13
The ltparametersgt Subsection 13
The ltlocationgt section 13
The lttypegt Subsection 14
The ltnearbycitiesgt Subsection 14
The ltweathergt Subsection 14
The ltspellinggt Subsection 14
The ltalphabetgt Subsection 15
The ltcategoryStatgt Subsection 15
Localcom Local Distribution Service (LDS) API Version | 33
Page | 3
The lterrorgt Subsection 15
The ltresultsetgt Subsection 15
The ltresultgt Subsection 16
The ltlocalgt Subsection 17
The ltextendedgt Subsection 18
CALLING LDS FOR PROFILE PAGE 19
The ltprofilegt Segment 21
SAMPLE CALLS 22
A Sample Call in C 22
A Sample Call in Java 23
A Sample Call in PHP 23
APPENDICES 25
Appendix A ndash XML Feed Results Example 25
Appendix B ndash Frequently Asked Questions 27
Localcom Local Distribution Service (LDS) API Version | 33
Page | 4
OVERVIEW The Localcom Local Distribution Service (LDS) application programming interface (API)
provides an open standards interface for use by developers at Localcom partner sites
This interface is referred to as the LDS API
The LDS API works with any platform or technology and gives developers full access to an
XML feed of local search results profile pages and advertising for all locations in the
United States Built on Localcom‟s proprietary search technology the LDS API connects
subscribers to a high-speed highly-reliable content-rich source of local business listings
and targeted local advertising
There are two LDS api endpoints Any new user needs to use the v2 api as it has more
features For example Json format is supported only in v2 api We also encourage existing
LDS user to upgrade to v2 api LDS v1 api is provided for backward compatibility purpose
for a period of time and will be dropped out later
LDS api endpoint V2
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
LDS call endpoint V1
httpldslocalcomldssearchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]ampref
errer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
This guide describes the calls in the LDS API and helps you understand the LDS data feed
on your web properties to maximize your revenues on local search traffic The major
sections in this guide are as follows
LDS Account Setup describes what you need to do before using the LDS API
LDS API Fundamentals provides basic information on the LDS API
Input Parameters describe the various required and optional parameters of an LDS
API call
Call Syntax describes the syntax of an LDS API call
Examples show various examples of LDS API input and the resulting XML output
Parameter Notes describe the syntax of an LDS API call
Info Section describes the ltinfogt section that appears within each XML response
This section may contain multiple subsections each of which may contain multiple
fields
o The ltparametersgt subsection
o The ltlocationgt subsection
o The ltspellinggt subsection
o The ltalphabetgt subsection
o The lterrorgt subsection
o The ltcategoryStatgt subsection
Localcom Local Distribution Service (LDS) API Version | 33
Page | 5
o The ltresultsetgt subsection
Calling LDS for Profile Page describes how to access the profile page of a courtesy
listing
Sample Calls provides a sample LDS API call in three different programming
languages C Java and PHP
Appendix A XML Feed Results Example provides an instance of the feed results
Appendix B Frequently Asked Questions answers commonly asked questions
Use this guides table of contents if youre looking for something specific If theres
something you need and can‟t find within this guide send your question to our customer
support at ldssupportlocalcom and well get you what you need
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 3
The lterrorgt Subsection 15
The ltresultsetgt Subsection 15
The ltresultgt Subsection 16
The ltlocalgt Subsection 17
The ltextendedgt Subsection 18
CALLING LDS FOR PROFILE PAGE 19
The ltprofilegt Segment 21
SAMPLE CALLS 22
A Sample Call in C 22
A Sample Call in Java 23
A Sample Call in PHP 23
APPENDICES 25
Appendix A ndash XML Feed Results Example 25
Appendix B ndash Frequently Asked Questions 27
Localcom Local Distribution Service (LDS) API Version | 33
Page | 4
OVERVIEW The Localcom Local Distribution Service (LDS) application programming interface (API)
provides an open standards interface for use by developers at Localcom partner sites
This interface is referred to as the LDS API
The LDS API works with any platform or technology and gives developers full access to an
XML feed of local search results profile pages and advertising for all locations in the
United States Built on Localcom‟s proprietary search technology the LDS API connects
subscribers to a high-speed highly-reliable content-rich source of local business listings
and targeted local advertising
There are two LDS api endpoints Any new user needs to use the v2 api as it has more
features For example Json format is supported only in v2 api We also encourage existing
LDS user to upgrade to v2 api LDS v1 api is provided for backward compatibility purpose
for a period of time and will be dropped out later
LDS api endpoint V2
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
LDS call endpoint V1
httpldslocalcomldssearchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]ampref
errer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
This guide describes the calls in the LDS API and helps you understand the LDS data feed
on your web properties to maximize your revenues on local search traffic The major
sections in this guide are as follows
LDS Account Setup describes what you need to do before using the LDS API
LDS API Fundamentals provides basic information on the LDS API
Input Parameters describe the various required and optional parameters of an LDS
API call
Call Syntax describes the syntax of an LDS API call
Examples show various examples of LDS API input and the resulting XML output
Parameter Notes describe the syntax of an LDS API call
Info Section describes the ltinfogt section that appears within each XML response
This section may contain multiple subsections each of which may contain multiple
fields
o The ltparametersgt subsection
o The ltlocationgt subsection
o The ltspellinggt subsection
o The ltalphabetgt subsection
o The lterrorgt subsection
o The ltcategoryStatgt subsection
Localcom Local Distribution Service (LDS) API Version | 33
Page | 5
o The ltresultsetgt subsection
Calling LDS for Profile Page describes how to access the profile page of a courtesy
listing
Sample Calls provides a sample LDS API call in three different programming
languages C Java and PHP
Appendix A XML Feed Results Example provides an instance of the feed results
Appendix B Frequently Asked Questions answers commonly asked questions
Use this guides table of contents if youre looking for something specific If theres
something you need and can‟t find within this guide send your question to our customer
support at ldssupportlocalcom and well get you what you need
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 4
OVERVIEW The Localcom Local Distribution Service (LDS) application programming interface (API)
provides an open standards interface for use by developers at Localcom partner sites
This interface is referred to as the LDS API
The LDS API works with any platform or technology and gives developers full access to an
XML feed of local search results profile pages and advertising for all locations in the
United States Built on Localcom‟s proprietary search technology the LDS API connects
subscribers to a high-speed highly-reliable content-rich source of local business listings
and targeted local advertising
There are two LDS api endpoints Any new user needs to use the v2 api as it has more
features For example Json format is supported only in v2 api We also encourage existing
LDS user to upgrade to v2 api LDS v1 api is provided for backward compatibility purpose
for a period of time and will be dropped out later
LDS api endpoint V2
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
LDS call endpoint V1
httpldslocalcomldssearchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]ampref
errer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
This guide describes the calls in the LDS API and helps you understand the LDS data feed
on your web properties to maximize your revenues on local search traffic The major
sections in this guide are as follows
LDS Account Setup describes what you need to do before using the LDS API
LDS API Fundamentals provides basic information on the LDS API
Input Parameters describe the various required and optional parameters of an LDS
API call
Call Syntax describes the syntax of an LDS API call
Examples show various examples of LDS API input and the resulting XML output
Parameter Notes describe the syntax of an LDS API call
Info Section describes the ltinfogt section that appears within each XML response
This section may contain multiple subsections each of which may contain multiple
fields
o The ltparametersgt subsection
o The ltlocationgt subsection
o The ltspellinggt subsection
o The ltalphabetgt subsection
o The lterrorgt subsection
o The ltcategoryStatgt subsection
Localcom Local Distribution Service (LDS) API Version | 33
Page | 5
o The ltresultsetgt subsection
Calling LDS for Profile Page describes how to access the profile page of a courtesy
listing
Sample Calls provides a sample LDS API call in three different programming
languages C Java and PHP
Appendix A XML Feed Results Example provides an instance of the feed results
Appendix B Frequently Asked Questions answers commonly asked questions
Use this guides table of contents if youre looking for something specific If theres
something you need and can‟t find within this guide send your question to our customer
support at ldssupportlocalcom and well get you what you need
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 5
o The ltresultsetgt subsection
Calling LDS for Profile Page describes how to access the profile page of a courtesy
listing
Sample Calls provides a sample LDS API call in three different programming
languages C Java and PHP
Appendix A XML Feed Results Example provides an instance of the feed results
Appendix B Frequently Asked Questions answers commonly asked questions
Use this guides table of contents if youre looking for something specific If theres
something you need and can‟t find within this guide send your question to our customer
support at ldssupportlocalcom and well get you what you need
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 6
LDS ACCOUNT SETUP
Before using the LDS API contact your Localcom representative to obtain information on
accessing the LDS server and to obtain valid access credentials (a login name and
password)
There are two methods to set up your LDS account The first (referred to as the traditional
method) requires you to white list your server IP and host URL while the second (referred
to as Method B) allows you to bypass the server IP and host URL check Depending on
how your account is set up be sure to follow the following associated guidelines
Traditional Method A (Using aff Parameter)
In general to get your account set up using this method the following information is
required to set up a Partner‟s LDS account
1 IP address or IP range of the server(s) which make(s) request to LDS
2 Host root URL that makes requests to LDS
As the above information will be used to valid all LDS calls be sure to use the correct
server IP and host root URL (that were provided for your account setup) otherwise errors
will be encountered for your LDS request
After your server IP and host URL were white-listed and your LDS account is setup an
affiliate ID will be provided to you You must use this affiliate ID for all of your LDS calls
New Method B (New Method Using appid Parameter)
With this method you do not need to provide us anything After the contract is signed
your LDS account will be set up and an appid will be provided to you You must use this
appid for all of your LDS calls
LDS API FUNDAMENTALS Once you understand the different parts of the API you can start creating your client
application This section describes some things to keep in mind when creating your client
application
Call Basics
The LDS API uses a REST-like interface This means that our LDS method calls are made
over the internet by sending HTTP GET or POST requests to the LDS API REST server Nearly
any computer language can be used to communicate over HTTP with the REST server A
HELPFUL TIP
If you are set up to use appid our system will not check the server IP and host URL However
the click rules still apply For more information please refer to the Frequently Asked Questions
(FAQ) section of this guide
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 7
request is made through a URL to the specified Localcom server which returns an XML or
JSON document via HTTP The data in the returned document will vary according to the
values of parameters passed in the API call (such as the keyword and the location for
example)
The LDS Sandbox
The LDS Sandbox is a non-production environment that provides full access to the LDS
API You can use it to develop and test your client applications without needing to worry
about how it might affect a production environment or production data For information
on accessing the Sandbox contact your Localcom representative
INPUT PARAMETERS
Required Parameters
Parameter Description
aff appid Aff is the affiliate ID assigned to you after your LDS account is set up
Appid is the application ID assigned to you after your LDS account is
set up
Note Depending on how your LDS account is created you must use
the correct identifier when calling LDS As noted above when appid is
used we do not need to white list the server IP and root host URL
keyword The key word or keywords (separated by commas) specifying what
to search for
location The geographic location associated with the search request This may
be a city and state combination a zip code a landmark an area
code or a specific street address United States locations only See
ldquoDetermine location in LDSrdquo later in this document for information on
how LDS handles cities provided without states
ip IP address of the user requesting the search This parameter is used by
Localcom to validate clicks against searches
Note This is not the server IP which calls LDS As a general guideline
LDS search end user ID and click end user IP must match as Localcom
click application detects the end user IP and this IP must match the
LDS IP parameter
referrer Root URL of the site displaying the result set This parameter is used to
validate clicks and searches and to ensure quality traffic
Example
wwwyourdomaincom
Note Be sure to specify the http referrer otherwise a click with an
empty http referrer is filtered out and not validated The referrer
parameter must match the root URL of the click http referrer
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 8
rp The full URL of a page making search request It is highly
recommended passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza+hut
26location3Dirvine+ca
httpuseragent User Agent of user performing search It is highly recommended
passing this parameter to get premium advertisers
Note The value must be url-encoded
Example
Mozilla4020(compatible20MSIE206020Windows20NT2051
20SV120Tablet20PC201720NET20CLR2010370520NET
20CLR20114322)
Optional Parameters
Parameters Description Valid Values
Default Value
Example
subaff Sub-affiliate Partner
can use this
parameter to
differentiate traffic
source
Alphanumeric
hyphen (-)
underscore (_)
and period ()
No default
ampsubaff=foobar
format API response format
in XML or json Json
format is supported
only in v2 api
Default value is
xml
ampformat=xml
ampformat=json
courtesysort Specifies how
courtesy results are
to be sorted
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquodistancerdquo |
ldquonamerdquo |
ldquorelevancerdquo
|rating
Default value is
relevance
ampcourtesysort=distance
courtesyfirstletter Allows courtesy
results to be filtered
by letter
See ldquoResults Sorting
Optionsrdquo later in this
document for more
information
ldquordquo any letter of
the alphabet or
ldquo0-9rdquo
No default
ampcourtesytfirstletter=a
maxresults Sets the maximum
number of results
received in each
Any integer
Default value is
10
ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 9
segment of the
feed
pagestart Sets the starting
ldquopagerdquo of results to
return based on the
setting of maxresults
The resultindex
parameter if
present takes higher
priority
Any integer
greater than
zero
Default value is 1
amppagestart=2
resultindex Specifies the
specific result at
which to start
returning results
Any integer
greater than
zero
No default
ampresultindex=11
parsekeyword Instructs the
Localcom parser to
look for a location
within the keyword
string
See ldquoDetermine
location in LDSrdquo for
more information
true | false
Default value is
false
ampparsekeyword=true
Note In order for the above request to be valid the user shall include a city and state
combination a zip code a landmark an area code or a specific street address
CALL SYNTAX The following shows the basic syntax (followed by an example) of LDS API calls that use
an aff and an appid
In the syntax shown below the [BracketedItems] are parameter place holders to be
replaced with appropriate data when actually making a request As described later in
this document there are other optional parameters that you may also include in your LDS
API calls
Query Syntax Using an aff
Example
httpldslocalcomldsv2searchjspaff=[aff]ampkeyword=[Keyword]amplocation=[Location]ampip=[IP]amp
referrer= [Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 10
Query Syntax Using an appid
Example
As illustrated above each request must include at least the following seven parameters
aff or appid keyword location ip referrer rp and httpuseragent
EXAMPLES
Input using a City and State
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt200ltexecutiontimegt
ltaffiliategttestltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltipgt1023251ltipgt
ltreferrergtwwwlocalcomltreferrergt
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=6325120735
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location392618amphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspappid=[appid]ampkeyword=[Keyword]amplocation=[Location]ampi
p=[IP]
ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
httpldslocalcomldsv2searchjspappid=4786E856-01C1-40C1-951D-
F06C731718C4ampkeyword=
hotelsamplocation=disneylandampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2Fwww
localcomresultaspx3Fkeyword3Dhotels26location3Ddisneylandamphttpuseragent=Mozilla
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=irvine+caampip=1023251
ampreferrer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza
26location3Dirvine+caamphttpuseragent=Mozillaampresultindex=0amppagestart=1ampmaxresults=10
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 11
ltrpgthttp3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26locat
ion3Dirvine+caltrpgt
lthttpuseragentgtMozillalthttpuseragentgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt10ltmaxresultsgt
ltparametersgt
ltldsgt
Input using a ZIP code and Maxresults of 20
Example XML Output
ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
ltinfogt
ltparametersgt
ltexecutiontimegt176ltexecutiontimegt
ltaffiliategttest ltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgt92618ltlocationgt
ltresultindexgt0ltresultindexgt
ltpagestartgt1ltpagestartgt
ltmaxresultsgt20ltmaxresultsgt
ltparametersgt
ltinfogt
ltldsgt
PARAMETER NOTES
Results Sorting Options
LDS allows you to specify how courtesy results in the returned XML feed are sorted Results
can be sorted by relevance distance business name or star rating You can also request
that results be returned by business name according to specific letters of the alphabet
Sorting Details
By including a ampcourtesysort= parameter in the request you can specify how courtesy
results in the returned XML feed are sorted By default (if you omit the parameter) the
results are sorted according to Localcom‟s proprietary combination of relevance (based
on keyword) and distance
httpldslocalcomldsv2searchjspaff=testampkeyword=pizzaamplocation=92618ampip=1023251ampref
errer=wwwlocalcomamprp=http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dpizza26lo
cation3D92618amphttpuseragent=Mozillaampmaxresults=20
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 12
If you include a ampcourtesysort= parameter the results are sorted the way you specify
ampcourtesysort=relevance lists the results by descending relevance to the specified
keyword In this case more relevant listings that are farther away from the search center
will be higher in the returned list than closer less relevant ones
ampcourtesysort=distance lists the closest results first
ampcourtesysort=name sorts the results alphabetically
ampcourtesysort=rating sorts the results from high to low by star rating (0 to 5 stars)
Distance
A search is performed using a 30-mile radius from the center of the specified search
location The search location (eg a city state zip or area code) is defined as the
population center of that geo If a specific address or landmark is provided the search
location is centered on that address or landmark Distances provided in the feed and
used to perform distance-based sorts are measured from the search location
Filtering by Letter
Localcom courtesy results can also be filtered by letters of the alphabet so that only a
limited subset of the results will be returned By passing in the parameter
ldquocourtesyfirstletterrdquo and providing a pound sign (ldquordquo) or a letter of the alphabet LDS will
return only results that start with a number or the specified letter This must be used with
the ldquoampcourtesysort=namerdquo parameter to create an alphabetically-sorted list of results
starting with a particular letter This allows users to create alphabetic filters in the UIs of
their sites See the ldquoUsing the Feed Resultsrdquo section for more information on the
ltalphabetgt section of the feed which can help to create a more intelligent alphabetic
filter
Location in LDS
If the location parameter is empty or invalid LDS uses GEOIP to determine the search
location However GEOIP may fail at times It is recommended to use
ldquoparsekeyword=truerdquo when location parameter is empty This will allow the LDS search
parser to look for location in the keyword string and to identify any locations contained
herein
If provided location parameter is empty or invalid and ldquoparsekeyword=truerdquo LDS uses
GEOIP to determine the user location If GEOIP is successful the GEOIP location is used for
the LDS location If GEOIP fails LDS parses location in keyword
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 13
THE ltinfogt SEGMENT
The ltinfogt segment within each returned XML feed contains general data about the
request made to LDS and the returned response This section may contain multiple
subsections each of which may contain multiple fields
The various subsections that may appear with the ltinfogt section are as follows
The ltparametersgt Subsection
Field Description
ltexecutiontimegt Time in milliseconds for LDS to process the request
Note This field can be used to determine the overall
performance of the system especially if you notice slow
response on the site Make a note of the times you see here
over several test queries
ltaffiliategt Affiliate ID used to call the feed
ltkeywordgt Keyword passed in for the search
ltlocationgt The ltlocationgt subsection specifying the location for the
search
Note As determined by passing parameters or through
GeoIP lookup
ltresultindexgt As passed in by the feed requestor the number of the first
courtesy result to be displayed
ltpagestartgt The page number of the first courtesy result to be displayed
as passed in the request
ltmaxresultsgt The number of results to display per page as passed in the
request
The ltlocationgt section
Field Description
ltstreetnumbergt Street (address) number as passed in the request or as
determined by the search parser
ltstreetgt Street name as passed in the request or as determined by
the search parser
ltcitygt City for the search as passed in the request or as determined
by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate city for the request and
display that here
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 14
ltstategt State for the search as passed in the request or as
determined by the search parser
Note If a zip code or landmark is passed the search parser
will determine the most appropriate state for the request and
display that here
ltzipcodegt Zipcode for the search as passed in the request or as
determined by the search parser
Note If a city state or landmark is passed the search parser
will determine the most appropriate Zip for the request and
display that here
ltareacodegt If passed in as a search parameter Otherwise it will not be
displayed
ltlandmarkgt If passed in as a search parameter Otherwise it will not be
displayed
ltlatitudegt Latitude of the center of the search radius as determined by
the search parser
ltlongitudegt Longitude of the center of the search radius as determined
by the search parser
The lttypegt Subsection
This subsection of the returned XML feed identifies the type of location used to determine
the search latitude and longitude
The value codes are 1 = Landmark 2 = Zipcode 4 = City 8 = Areacode 16 = State The
value codes are additive so a value of ldquo20rdquo indicates that both a City (4) and State (16)
were used
Example lttypegt20lttypegt
The ltnearbycitiesgt Subsection
This subsection of the returned XML feed lists the names of up to 10 cities near the
business‟ location Each name is enclosed within a ltlocationgtltlocationgt delimiter pair
Example ltnearbycitiesgtltlocationgtEast Irvine CAltlocationgtltlocationgtTustin
CAltlocationgtltlocationgtAliso Viejo CAltlocationgtltnearbycitiesgt
The ltweathergt Subsection
This subsection of the returned XML feed displays the current weather conditions of the
business‟ location
Example ltweathergtltweathergt
The ltspellinggt Subsection
This subsection of the returned XML feed displays alternate spelling suggestions as
determined by the search parser If a user has misspelled a common word a list of
alternatives will appear in this section These may be used by the web site‟s front end to
provide users with a clickable list of alternative spellings
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 15
Example ltspellinggtltspellinggt
The ltalphabetgt Subsection
This subsection of the returned XML feed is a single field containing a list of letters and
numerals (0-9) The letters in this list represent the letters by which a user may filter the
courtesy results list For example if a business in the results set is ldquoAcme Flowersrdquo then ldquoArdquo
would appear in the ltalphabetgt section If no business in the result set begins with ldquoZrdquo
then ldquoZrdquo will not appear in the list This can be used in conjunction with the courtesysort
and courtesyfirstletter parameters described above to create alphabetized filtered lists
of courtesy results
For an example of how this list is used in actual practice visit the search results page of
Localcom Try searching for less-common business types and you will see a more limited
set of letters returned in this section
Example ltalphabetgt0-9ABCDEFGHIJKLMNOPQRSTUVWYltalphabetgt
The ltcategoryStatgt Subsection
This subsection of the returned XML feed displays the category statistics for the courtesy
results It displays the category bdc the category name and the number of returned
items associated with the bdc You can use this information in conjunction with category
filtering of courtesy results
Example ltcategoryStatgtltcategorygtltbdcgt25070200ltbdcgt lttitlegtFlorists amp
Flowerslttitlegtltcountgt558ltcountgtltcategorygtltcategorygtltbdcgt10110300ltbdcgtlttitlegt
Ornamental Nursery Serviceslttitlegtltcountgt152ltcountgtltcategorygtltcategoryStatgt
The lterrorgt Subsection
This subsection of the returned XML feed displays feed errors in a human-readable format
Use these error descriptions when reporting feed problems to your Localcom
representative
Example lterrorgtlterrorgt
The ltresultsetgt Subsection
This subsection of the returned XML feed contains all of the advertising and business listing
results for the feed It is divided into several ltresultsetgt segments each of which contains
a number of results Reading in these segments will provide different kinds of listings that
can be displayed on a Web site‟s results page
There are two parameters in each resultset
1 Segment ndash indicates the type of result returned for that resultset
2 Total ndash indicates the total number of results returned in that section for the query
regardless of the number actually displayed in the feed (as determined by the
maxresults parameter)
Valid values for the segment parameter are
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 16
Value Description
Localppc Displays local pay-per-click ads These ads are those attached to a
particular geography and sorted by bid price
Nationalppc Displays national pay-per-click ads These ads are those not attached to
a particular geography and sorted by bid price
Localfavorite Displays local favorite business listings based on location
Localbest Displays local best business listings based on location
PartnerA Displays local business listings from Partner A
PartnerB Displays pay-per-click ads from Partner B
Sponsored Displays pay-per-call ads from Partner C
PartnerD Displays pay-per-click ads from Partner D
Featured Displays pay-per-click ads from Partner E These ads may be not sorted by
bid price
Subscription Displays subscription ads contained in the Localcom ad center that
have preferred ad placement in the Featured Sponsor section of
wwwLocalcom
Courtesy Displays Localcom‟s business listings results sorted according to the
parameters specified in the feed request
Each of the above segments adheres to the same basic XML layout
Note Some of the above segments may not show in the XML result depending on your
account setup Ask a Localcom representative about which segments should appear in
your feed result Segments that contain locally-oriented results have additional fields of
data provided
The ltresultgt Subsection
There is one ltresultgt subsection for each locally-based advertisement or listing that
satisfies the search criteria specified in the request
Each ltresultgt subsection in the returned XML feed includes the following fields which
may or may not be populated for a particular result
1 Listing title or business name
2 Listing description
3 Click bid value
4 Click URL
5 Display URL
6 Position of the listing in the results list
7 Rating icon
8 Phone track URL
9 External review URL
10 External profile URL
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 17
Field Description
lttitlegt The title of the advertisement or the name of the business
associated with the listing
ltdescriptiongt The text of the advertisement or a description of the listing (if
available)
ltbidgt The bid value for a click (or call) for the advertisement
Note Bid values for pay-per-call ads are for calls only not
clicks
ltclickurlgt The URL created by Localcom‟s click processing system that
captures data about each click and redirects the user to the
requested ad Should you want to learn about how LDS tracks
the number of clicks for advertisement please refer to
Appendix B Frequently Asked Questions
ltdisplayurlgt The URL to be displayed by the Web site This creates a better
appearance than the ClickURL
ltpositiongt The position of the advertisement or listing in the results list as
determined by the sorting rules applied
ltrating_icongt A rating icon for the business
ltphone_track_urlgt The URL of the telephone track of the business
ltexternal_review_urlgt The URL of an external review of the business
ltexternal_profile_urlgt The URL of an external profile of the business
ltextendedgt A subsection specifying additional information about the
advertisement or listing
The ltresultgt subsection also includes a ltlocalgt and ltextendedgt subsection which may
or may not be populated for a particular result
The ltlocalgt Subsection
The ltlocalgt subsection in the returned XML feed for each locally-based advertisement or
listing specifies geographical information for the business It includes the following fields
which may or may not be populated for a particular result
1 Name
2 Address
3 City
4 State
5 Zipcode
6 Phone
7 Latitude
8 Longitude
9 MapURL
10 Distance
The following table summarizes these fields
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 18
Field Description
ltnamegt The business‟ name especially if different from the ad title
ltaddressgt The street address of the business
ltcitygt The city of the business
ltstategt The state of the business
ltzipcodegt The zip code of the business
ltphonegt The telephone number of the business
ltlatitudegt The latitude of the business‟ location
ltlongitudegt The longitude of the business‟ location
ltmapurlgt A URL provided by Localcom that points to the free map
provided at mapslocalcom
ltdistancegt The distance in miles of the business from the center of the
search location
Note This is provided only for those listings or ads with a
physical address
The ltextendedgt Subsection
The ltextendedgt subsection in the returned XML feed for each locally-based
advertisement or listing specifies additional information about the advertisement or listing
It includes the following fields which may or may not be populated for a particular result
1 Advertiser ID
2 Listing ID
3 Category
4 Category text description
5 A_url
6 Web url
7 Result description
8 Star rating
9 Review description
The following table summarizes these fields
Field Description
advertiserid The id of the advertiser
listingid The id of the listing
category A category number (BDC code) associated with the business
categorynnnnnnnn The category text description for the BDC number nnnnnnnn
A_url The web url of the business
weburl The web url of the business
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 19
Note If both A_url and weburl are available we recommend
that you use A_url for the display
resultDesc Description of the business
starRating Average review rating score ranges from 0 to 5 stars
reviewDesc Description of the most recent review snip
Each data item within an extended subsection is a key and value pair For example a
listing ID is specified within an extended subsection as follows
ltdata key=listingid value=65435826 gt
If a particular data item has multiple attributes such as a business category has both a
category number (BDC code) and a text description you use multiple key and value
pairs to show the linkage
In the following example there are four category numbers (BDC codes) and four
category text descriptions Each category number is linked to its text description by two
key and value pairs Category ldquo10040102rdquo is linked to ldquoHorticultural Plantsrdquo Category
ldquo10110212rdquo is linked to ldquoPlants Indoor Wholesalerdquo Category ldquo11210604rdquo is linked to ldquoSilk
Flowers amp Plants Rental amp Leasingrdquo Category ldquo10110214rdquo is linked to ldquoPlants Wholesalerdquo
ltdata key=category value=10040102 gt
ltdata key=category10040102 value=Horticultural Plants gt
ltdata key=category value=10110212 gt
ltdata key=category10110212 value=Plants Indoor Wholesale gt
ltdata key=category value=11210604 gt
ltdata key=category11210604 value=Silk Flowers amp Plants Rental amp Leasing gt
ltdata key=category value=10110214 gt
ltdata key=category10110214 value=Plants Wholesale gt
CALLING LDS FOR PROFILE PAGE Each result in ldquocourtesyrdquo section has a profile page which can be called by way of the
LDS API This section summarizes how to call such a profile page
Input Parameters
Syntax
httpldslocalcomldsv2searchjspaff=[Aff]amplistingid=[Listingid]ampkeyword=[Keyword]amplocation
=[Location]ampip=[IP]ampreferrer=[Referrer]amprp=[ReferrerFullUrl]amphttpuseragent=[HttpUserAgent]
HELPFUL TIP
Note If you need to call LDS for profile data please make sure to ask Localcom
representative for a profile page affiliate id This identifier is different from the SERP affiliate
identifier
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 20
1 aff or appid - required
2 listingID - required
3 keyword - optional
4 location - optional
5 ip - required
6 referrer ndash required
7 rp ndash required
8 httpuseragent ndash required
Notes 1) The only different parameter between calling results for SERP and profile page is
listingid which contains a listingid field under an ltextendedgt section of ltcourtesygt
segment 2) Keyword and Location parameters are optional 3) As is the case for local-
search-results calls the subaff parameter can be used to differentiate traffic source for
profile-page calls
Example URL Using aff
httpldslocalcomldsv2searchjspaff=test_pamplistingid=52284088ampip=1023251ampreferrer=wwwl
ocalcomamprp=http3A2F2Fwwwlocalcomdetailsaspxamphttpuseragent=Mozilla
Example XML Output
ltxml version=10 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2008 Localcom Corporationltcopyrightgt
+ ltinfogt
- ltprofilegt
ltlistingIdgt52284088ltlistingIdgt
ltagencyIdgtAXltagencyIdgt
ltnamegtThai Vegetarian Cuisineltnamegt
ltdescription gt
ltaddressgt14370 Culver Drltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495518222ltphonegt
ltlatitudegt33705741ltlatitudegt
ltlongitudegt-117786563ltlongitudegt
ltadvertiserIdgt0019337143ltadvertiserIdgt
ltemailAddress gt
lthours gt
ltcreditCards gt
ltlanguages gt
ltseniorDiscount gt
ltsic gt
ltnaics gt
lturls gt
- ltcategoriesgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 21
ltcategory id=16030000gtRestaurantsltcategorygt
ltcategoriesgt
- ltbreadcrumbgt
ltcategory level=1 id=16000000gtFood And Diningltcategorygt
ltcategory level=2 id=16030000gtRestaurantsltcategorygt
ltbreadcrumbgt
- ltreviewsgt
+ ltreview partner=LocaLReview agencyId=LM reviewId=252gt
ltreviewsgt
ltlogoFullLocation gt
+ ltweb_referencesgt
ltoffers gt
ltcoupons gt
ltprofilegt
- ltresultsetsgt
+ ltresultset segment=partnerB total=6gt
+ ltresultset segment=partnerD total=16gt
+ ltresultset segment=localppc total=33gt
ltresultsetsgt
ltldsgt
The ltprofilegt Segment
There is a new segment named ltprofilegt that contains profile data for a locally-based
advertisement or listing Common fields for this segment include the following fields
which may or may not be populated for a particular result
Field Description
Listingid Id of the profile listing
Name Business name of the listing
Address Address of the listing
City City of the listing
State State of the listing
Zipcode Zip code of the listing
Phone Phone number of the listing
Latitude Latitude of the listing location
Longitude Longitude of the listing location
Emailaddress Email address of the listing
Hours Hours of operations of the listing
Creditcards Credit card accepted by the listing
Urls Urls of the listing
Categories Categories of the listing
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 22
Field Description
Breadcrumb Pick the main category and list its parent category as
breadcrumb format
The breadcrumb can be used as a category
relationship drill down The lower level category is the
parent of a larger one
Reviews Reviews of the business listing
Content More detailed description of the business
Web_references Web references for the listing
SAMPLE CALLS The topics that follow show examples of an LDS API call in three different programming
languages C Java and PHP
A Sample Call in C
The following C LDS API call requests results for flower retailers near Irvine CA
HttpWebRequest req
HttpWebResponse res = null
StreamReader reader
StringBuilder response
try
req=WebRequestCreate(httpldslocalcomldsv2searchjspaff=testampkeyword
=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=
http3A2F2Fwwwlocalcomresultaspx3Fkeyword3Dflowers26
location3Dirvine+caamphttpuseragent=Mozilla) as HttpWebRequest
res = requestGetResponse() as HttpWebResponse
if (reqHaveResponse == true ampamp res = null)
reader = new StreamReader(resGetResponseStream())
response = new StringBuilder(readerReadToEnd())
Parse response here
catch (WebException wex)
Handle exception here
finally
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 23
A Sample Call in Java
The following Java LDS API call requests results for flower retailers near Irvine CA
A Sample Call in PHP
The following PHP LDS API call requests results for flower retailers near Irvine CA
if (res = null)
resClose()
Using Apache httpclient module
HttpClient client = new HttpClient()
HttpMethod method =
newGetMethod(httpldslocalcomldsv2searchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla)
try
clientexecuteMethod(method)
if (methodgetStatusCode() == HttpStatusSC_OK)
String response = methodgetResponseBodyAsString()
Parse response here
catch (IOException e)
Handle exception here
finally
methodreleaseConnection()
ltphp
$r = new HttpRequest(bdquohttpldslocalcomldssearchjspaff=testampkeyword=flowers
amplocation=irvine+caampip=6325120735ampreferrer=wwwlocalcomamprp=http3A2F2F
www localcomresultaspx3Fkeyword3Dflowers26location3Dirvine+caamphttpuseragent=
Mozilla HttpRequestMETH_GET)
try
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 24
$r-gtsend()
if ($r-gtgetResponseCode() == 200)
$res = $r-gtgetResponseBody())
Parse response here
catch (HttpException $ex)
Handle exception
gt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 25
APPENDICES
Appendix A ndash XML Feed Results Example
ltxml version=10 encoding=UTF-8 gt
- ltldsgt
ltcopyrightgtCopyright copy 1999-2011 Localcom Corporationltcopyrightgt
- ltinfogt
- ltparametersgt
ltexecutionTimegt1478ltexecutionTimegt
ltaffiliategtlocm_sltaffiliategt
ltkeywordgtpizzaltkeywordgt
ltlocationgtirvine caltlocationgt
ltresultIndexgt1ltresultIndexgt
ltpageStartgt1ltpageStartgt
ltmaxResultsgt10ltmaxResultsgt
ltparametersgt
- ltlocationgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92618ltzipCodegt
ltlatitudegt33679632ltlatitudegt
ltlongitudegt-117791492ltlongitudegt
lttypegt20lttypegt
- ltnearbyCitiesgt
ltlocationgtEast Irvine CAltlocationgt
ltlocationgtTustin CAltlocationgt
ltlocationgtSanta Ana CAltlocationgt
ltlocationgtNewport Coast CAltlocationgt
ltlocationgtLaguna Woods CAltlocationgt
ltnearbyCitiesgt
ltlocationgt ltalphabetgtABCDEFGHIJKLMNOPQRSTUVWXYZltalphabetgt
ltsearchIdgtc3a0a6c5-f59e-44aa-a3b8-218c4a6bbb9eltsearchIdgt
ltinfogt
- ltresultSetsgt
- ltresultSet segment=courtesy total=1142gt
- ltresultgt
lttitlegtLamppost Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt1ltpositiongt
ltaddressgt4230 Barranca Pkwyltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495590900ltphonegt
ltlatitudegt3368126669098593ltlatitudegt
ltlongitudegt-11780436256658123ltlongitudegt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 26
ltdistancegt075ltdistancegt
- ltextendedgt
ltdata key=category value=16163600 gt
ltdata key=listingid value=104892286 gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltextendedgt
ltresultgt
- ltresultgt
lttitlegtZ Pizzalttitlegt
ltbidgt0ltbidgt
ltpositiongt2ltpositiongt
ltaddressgt5365 Alton Pkwy Ste Iltaddressgt
ltcitygtIrvineltcitygt
ltstategtCAltstategt
ltzipCodegt92604ltzipCodegt
ltphonegt9495511555ltphonegt
ltlatitudegt3367129722535065ltlatitudegt
ltlongitudegt-11778912188923074ltlongitudegt
ltdistancegt059ltdistancegt
- ltextendedgt
ltdata key=starRating value=3666667 gt
ltdata key=category value=16163600 gt
ltdata key=listingid value=80457527 gt
ltdata key=Acxiom_displayurl value=wwwzpizzacom gt
ltdata key=Acxiom_url value=wwwzpizzacom gt
ltdata key=category16163600 value=Pizza Restaurant gt
ltdata key=url value=Acxiom gt
ltextendedgt
ltresultgt
ltresultSetgt
- ltresultSet segment=nationalppc total=6gt
- ltresultgt
lttitlegtDominoamp39sreg ltbgtPizzaltbgt Deliverylttitlegt
ltdescriptiongtDelivering Quality from the Farm to Your Front Door Order Yours
Todayltdescriptiongt ltbidgt021ltbidgt
- ltclickUrlgt ltclickUrlgt
ltdisplayUrlgtwwwDominoscomltdisplayUrlgt
ltpositiongt1ltpositiongt
ltresultgt
- ltresultgt
ltresultSetgt
ltresultSetsgt
ltldsgt
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32
Localcom Local Distribution Service (LDS) API Version | 33
Page | 27
Appendix B ndash Frequently Asked Questions
1 With the traditional method what information is required in order to set up an
account
The following information is required to set up a Partner‟s LDS account using the
traditional method
a IP address of the server (or IP range of the servers) which will make requests to
LDS If the IP address (or range of addresses) is not white listed in our system you
will get the following response
lterrorgtFailed AllowedAffiliateIpFilterlterrorgt
b Host root URL that makes request to LDS If the root url is not white listed in our
system you will get the following response
lterrorgtFailed AllowedReferrerFilterlterrorgt
Note If you are using appid for authentication you will not get the above error If
the appid is not valid you will get the following response
lterrorgtInvalid AppId lterrorgt
2 How does LDS monitor ldquoclicksrdquo for advertisement
Localcom uses clicklocalcom as the click URL for all advertisements Therefore be
sure to use the clicklocalcom URL for any monetization event The clicklocalcom
application detects the HTTP referrer and end user IP addresses via the HTTP header
Here are a few guidelines
Be sure to send HTTP referrer in your application as clicklocalcom needs HTTP
referrer in HTTP header to validate the click A click with empty HTTP referrer is
filtered out Do not throw out or hide the HTTP referrer A network tool such as
Fiddler is recommended to be used to check the HTTP referrer
The LDS search referrer and the click HTTP referrer must match There is a referrer
parameter in LDS Referrer is root URL of site displaying the result The LDS referrer
parameter must match the root URL of the click HTTP referrer
The LDS search end user IP and the click end user IP must match There is an IP
parameter in LDS The localcom click application detects the end user IP and
that IP must match the LDS IP parameter
The LDS click filter codes are as follows
ipDoesNotMatchSearch = 1
ReferrerDoesNotMatchSearch = 2
ExceededMaxClicksDay = 16
DoubleClick = 32