Local.com XML Feed Guidelines JAN 12

27
LOCAL DISTRIBUTION SERVICES (LDS) API Version: 3.3 Last Updated: Jan 2012

Transcript of Local.com XML Feed Guidelines JAN 12

Page 1: Local.com XML Feed Guidelines JAN 12

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

Page 2: Local.com XML Feed Guidelines JAN 12

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

Page 3: Local.com XML Feed Guidelines JAN 12

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

Page 4: Local.com XML Feed Guidelines JAN 12

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

Page 5: Local.com XML Feed Guidelines JAN 12

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

Page 6: Local.com XML Feed Guidelines JAN 12

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

Page 7: Local.com XML Feed Guidelines JAN 12

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

Page 8: Local.com XML Feed Guidelines JAN 12

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

Page 9: Local.com XML Feed Guidelines JAN 12

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

Page 10: Local.com XML Feed Guidelines JAN 12

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

Page 11: Local.com XML Feed Guidelines JAN 12

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

Page 12: Local.com XML Feed Guidelines JAN 12

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

Page 13: Local.com XML Feed Guidelines JAN 12

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

Page 14: Local.com XML Feed Guidelines JAN 12

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

Page 15: Local.com XML Feed Guidelines JAN 12

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

Page 16: Local.com XML Feed Guidelines JAN 12

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

Page 17: Local.com XML Feed Guidelines JAN 12

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

Page 18: Local.com XML Feed Guidelines JAN 12

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

Page 19: Local.com XML Feed Guidelines JAN 12

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

Page 20: Local.com XML Feed Guidelines JAN 12

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

Page 21: Local.com XML Feed Guidelines JAN 12

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

Page 22: Local.com XML Feed Guidelines JAN 12

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

Page 23: Local.com XML Feed Guidelines JAN 12

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

Page 24: Local.com XML Feed Guidelines JAN 12

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

Page 25: Local.com XML Feed Guidelines JAN 12

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

Page 26: Local.com XML Feed Guidelines JAN 12

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

Page 27: Local.com XML Feed Guidelines JAN 12

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