Multimap logo Multimap API V1.2 Web Services Documentation - Searching


Searching Overview

The Multimap API V1.2 Searching web service module allows you to query data sources such as Multimap-hosted data tables. Both spatial and non-spatial queries are available.


Searching Parameters

The Searching web service parameters, their description and values are as follows:

Table 1. Search Parameters

Parameter Description Valid values Mandatory
bbThis parameter refers to a string to specify the bounding box for the search. String of format: min_lon,
min_lat; max_lon,
max_lat
No
countThis parameter specifies the number of records to display per page (20 by defaults).IntegerNo
countryCodeThis parameter specifies the two-letter ISO country code for the input address. It returns a result which is the center of the spatial search. Two-letter ISO country codeNo
dataSourceThis parameter specifies the data source to use. It is possible to search multiple data sources in one request by specifying a comma-separated list. Each dataSource has its own RecordSet element in the XML document that returns results. String (defaults to your table of addresses)No
distanceUnitsThis parameter specifies the units in which the maxDistance and minDistance parameters are shown.'KM' or 'miles'No
formatThis parameter specifies that if format is 'compact', the record details are not returned; only a count of the total number of matching records (ignoring paging) is returned.'compact' or 'normal'No
latThis parameter specifies the latitude of the search center point. It returns a result which is the center of the spatial search.Float; -90 to 90No
locale This determines the appearance of labels and other text on a static map, based on settings for language and geographic area. Any of the set of codes prescribed in the list of permissible locale values No
logicThis parameter specifies the logic operator to use if more than one field filter is provided ("AND" by default). 'AND' or 'OR' or comma-separated listNo
lonThis parameter specifies the longitude of the search center point. It returns a result which is the center of the spatial search.Float; -180 to 180No
maxDistanceThis parameter specifies the maximum distance a record must be from the search point ("KM" by default).FloatNo
minDistanceThis parameter specifies the minimum distance a record must be from the search point ("KM" by default).FloatNo
orderByFieldsThis parameter specifies a comma-separated list of field names by which ordering should be applied.String or comma-separated listNo
orderByOrderThis parameter specifies a comma-separated list of directions (ascending or descending) in which records are to be sorted. This should match with the orderByFields value. Comma-separated list of asc or desc valuesNo
returnFieldsThis parameter specifies a comma-separated list of field names that should appear in the result page; it returns all fields by default. String or comma-separated listNo
routeModesThis parameter specifies whether to generate a driving and/or walking route (where available); it gives a driving route by default. You can also calculate and display the driving or walking distance or duration in the XML response depending on the parameters specified.Comma-separated list ("driving" or "walking")No
startIndexThis parameter specifies the index of the first record to display (starts at and defaults to 1).IntegerNo

Table 2. Search Filtering Parameters

[Note: Please replace "parameter_[COUNTER]" with incremental numbers such as parameter_1, parameter_2,...,parameter_n. Here, parameter_1 is used for the first route point and parameter_2 for the second route point.]

Parameter Description Valid values Mandatory
compoundOrderThis parameter specifies the order of operation by which you wish to evaluate your selected database fields.String; comma-separated listNo
compoundThresholdThis parameter specifies the number of matching records that must be found before the compound query halts.IntegerNo
fieldname_[COUNTER]This parameter specifies the name of the field in the data source on which to filter, such as fieldname_1, fieldname_2....StringNo
operator_[COUNTER]This parameter specifies the operator to be used in the field filter, such as operator_1, operator_2....StringNo
preSearchDataSourceThis parameter specifies which data source is to be used in a pre-search. The result of that search will then be used as an input to the main search action.StringNo
preSearchFiltersThis parameter specifies which field filters are to be used in a pre-search. The result of that search will then be used as an input to the main search action.StringNo
resultSetSizeThis parameter is used when queries based on specific point also have 'order by' settings to obtain a result set of the specified size, sorted by distance from the original point.IntegerNo
value_[COUNTER]This parameter specifies the value used in the field filter search, such as value_1, value_2....StringNo

Table 3. Geocode Parameters for Searching

Parameter Description Valid values Mandatory
cityThis parameter specifies the city, town or suburb for the input address. The result it returns is the center of the spatial search.StringNo
postalCodeThis parameter specifies the postal code for the input address. The result it returns is the center of the spatial search.StringNo
qsThis parameter specifies an address or place name entered as a single string, preferably used in conjunction with countryCode. The result it returns is the center of the spatial search.StringNo
regionThis parameter specifies the region for the input address; it is a synonym for state. The result it returns is the center of the spatial search.StringNo
stateThis parameter specifies the state for the input address; it is a synonym for region. The result it returns is the center of the spatial search.StringNo
streetThis parameter specifies the street, optionally including a building number, for the input address. The result it returns is the center of the spatial search.StringNo
ZIPThis parameter specifies the ZIP code for the input address; it is a synonym for postalCode. The result it returns is the center of the spatial search.StringNo

Searching Operators

Searching web services enable you to use one or more search operators to produce the desired search results. A detailed list of Search operators is as follows:

Operator Example Filter Description
eqfieldname_1=client_id&operator_1=eq&value_1=100 Equals; it returns the records where the concerned field exactly matches a given pattern. In this example, records where client_id equals "100" are returned.
ltfieldname_1=client_id&operator_1=lt&value_1=100 Less than; it returns the records where the concerned field is less than the specified value. In this example, records where client_id is less than "100" are returned.
gtfieldname_1=client_id&operator_1=gt&value_1=500 Greater than; it returns the records where the concerned field is greater than the specified value. In this example, records where client_id is more than "500" are returned.
notfieldname_1=country&operator_1=not&value_1=uk Not; it returns the records where the concerned field is not the same as the specified value. In this example, records where country is not "UK" are returned.
lefieldname_1=geoquality&operator_1=le&value_1=9 Less than or equal; it returns the records where the concerned field is either less than or equal to the specified value. In this example, records where geoquality is less than or equal to "9" are returned.
gefieldname_1=geoquality&operator_1=ge&value_1=9 Greater than or equal; it returns the records where the concerned field is either greater than or equal to the specified value. In this example, records where geoquality is greater than or equal to "9" are returned.
infieldname_1=client_id&operator_1=in&value_1=100,114,128 Matches against a comma-separated list of values; it returns the records where the concerned field matches against the comma-separated list. In this example, records where client_id matches "100", "114" and "128" are returned.
nullfieldname_1=street&operator_1=null Value is null; it returns the records where the concerned field is null. In this example, records where street is "null" are returned.
notnullfieldname_1=street&operator_1=notnull Value is not null; it returns the records where the concerned field is "not null". In this example, records where street is not null are returned.
containsfieldname_1=name
&operator_1=contains&value_1=tate
Contains; it returns the records where the concerned field contains the whole specified word. In this example, records where name contains "tate" are returned.
startswithfieldname_1=street&operator_1=startswith&value_1=gough Starts with; it returns the records where the concerned field starts with the specified value. In this example, records where street starts with "glough" are returned.
endswithfieldname_1=street&operator_1=endswith&value_1=square Ends with; it returns the records where the concerned field ends with the specified value. In this example, records where street ends with "square" are returned.
likefieldname_1=name
&operator_1=like&value_1=*tate
Like or partial match; it returns the records where the concerned field matches a given pattern. It supports wildcard characters. In this example, records where name matches the pattern "*tate" are returned.
Please note that the like operator uses 'wildcard' characters to match patterns, so that, for example, "like *tim*" equates to "contains tim".
slfieldname_1=name&operator_1=sl&value_1=hello Sounds like; it compares the sound and returns the records where the concerned field sounds like the specified value. In this example, records where name sounds like "hello" or "hulaw" or similar sounding values are returned.
cofieldname_1=name&operator_1=co&value_1=abcd Character order; it returns the records where the concerned field contains the specified characters in alphabetical order. In this example, records where name contains characters "abcd" in that order are returned.
comcompound Please refer to the section on Compound Searching
regexpfieldname_1=name&operator_1=regexp&value_1=^r.*mu.*$ Regular expression; it returns the records where the concerned field matches the specified pattern. In this example, records where name starts with "r" and after that has "mu" at some point are returned.
notlikefieldname_1=street&operator_1=notlike&value_1=%road Not like; it returns the records where the concerned field does not match the specified pattern. In this example, records where street that does not end with "road" are returned.
Please note that the notlike operator uses 'wildcard' characters to match patterns.
beginning_slfieldname_1=name&operator_1=beginning_sl&value_1=man Beginning sounds like; it returns the records where the beginning of the concerned field sounds like the specified value. In this example, records where beginning of name sounds like "man" are returned.

Searching Examples

Example 1

Here is an example of a URL requesting a search on the partial postcode EC4 in London, Great Britain:

http://clients.multimap.com/API/search/1.2/[api_key]?qs=EC4&city=London&countryCode=GB

Response 1

The URL shown above returns the following response:

<?xml version="1.0" encoding="UTF-8" ?>
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="7"> <Record counter="1"> <Fields> <Field name="client_id">GB01</Field> <Field name="name">Tate Gallery</Field> <Field name="street">Millbank</Field> <Field name="town">London</Field> <Field name="pc">SW1P 4RG</Field> <Field name="state" /> <Field name="country">GB</Field> <Field name="telephone">44 0207 887 8000</Field> <Field name="fax" /> <Field name="url" /> <Field name="id">10</Field> <Field name="GeoQuality">4</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">cp071</Field> </Fields> <Distance> <Miles>2.03</Miles> <KM>3.27</KM> </Distance> <Point> <Lat>51.49087</Lat> <Lon>-0.12718</Lon> </Point> </Record> <Record counter="2"> <Fields> <Field name="client_id">GB03</Field> <Field name="name">Royal Albert Memorial Museum & Art Gallery</Field> <Field name="street">Queen Street</Field> <Field name="town">Exeter</Field> <Field name="pc">EX4 3RX</Field> <Field name="state" /> <Field name="country">GB</Field> <Field name="telephone">+44 (0)1392 665858</Field> <Field name="fax">+44 (0)1392 421252</Field> <Field name="url" /> <Field name="id">9</Field> <Field name="GeoQuality">4</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">cp071</Field> </Fields> <Distance> <Miles>158.60</Miles> <KM>255.25</KM> </Distance> <Point> <Lat>50.72529</Lat> <Lon>-3.53253</Lon> </Point> </Record> ... <Record counter="7"> <Fields> <Field name="client_id">IT01</Field> <Field name="name">Museo Bagatti Valsecchi</Field> <Field name="street">10 Via Santo Spirito</Field> <Field name="town">Milan</Field> <Field name="pc">20121</Field> <Field name="state" /> <Field name="country">IT</Field> <Field name="telephone">39 12 34 56 78 90</Field> <Field name="fax" /> <Field name="url" /> <Field name="id">6</Field> <Field name="GeoQuality">1i</Field> <Field name="GeocodeDate">2007-04-05</Field> <Field name="GeocodeSource">IT06_1</Field> </Fields> <Distance> <Miles>596.24</Miles> <KM>959.56</KM> </Distance> <Point> <Lat>45.46985</Lat> <Lon>9.19461</Lon> </Point> </Record> </RecordSet> </RecordSets>

Notes on Response 2

Code Notes
<?xml version="1.0" encoding="UTF-8" ?> The XML declaration specifies the XML version being used and makes a reference to UTF-8 (eight-bit Unicode Transformation Format), which supports any character in the Unicode standard.
<RecordSets xmlns="http://clients.multimap.com/API"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd">
<RecordSet dataSource="[datasource1]" totalRecordCount="7">
This section refers to the parent element of the document and defines the XML name space.
The xsi:schemaLocation section defines the XML location schema.
The dataSource element specifies the data source to use. It is possible to search multiple data sources in one request by specifying a comma-separated list, as shown in the following example.
The totalRecordCount element specifies the number of matched results or records returned by the request.
<Record counter="1">
<Fields>
<Field name="client_id">GB01</Field>
<Field name="name">Tate Gallery</Field>
<Field name="street">Millbank</Field>
<Field name="town">London</Field>
<Field name="pc">SW1P 4RG</Field>
<Field name="state" />
<Field name="country">GB</Field>
<Field name="telephone">44 0207 887 8000</Field>
<Field name="fax" />
<Field name="url" />
<Field name="id">10</Field>
<Field name="GeoQuality">4</Field>
<Field name="GeocodeDate">2007-04-05</Field>
<Field name="GeocodeSource">cp071</Field>
</Fields>
<Distance>
<Miles>2.03</Miles>
<KM>3.27</KM>
</Distance>
<Point>
<Lat>51.49087</Lat>
<Lon>-0.12718</Lon>
</Point>
</Record>
The counter element refers to the record number.

The name element specifies the name of the parameter returned by the request.

















The Point element refers to a location in decimal degrees of latitude and longitude .
</RecordSet>
</RecordSets>
The RecordSet and RecordSets elements close here.


Example 2

In response to a successful search with multiple data sources:

http://clients.multimap.com/API/search/1.2/[api_key]?qs=EC4&city=London&countryCode=GB&dataSource=[datasource1],
[datasource2]

Response 2

<?xml version="1.0" encoding="UTF-8" ?> 
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
Xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="8"> <Record counter="1"> <Fields> <Field name="client_id" /> <Field name="name">Museum of London</Field> <Field name="street">150 London Wall</Field> <Field name="town">London</Field> <Field name="pc">EC2Y 5HN</Field> <Field name="state" /> <Field name="country">GB</Field> <Field name="telephone">0870 444 3852</Field> <Field name="fax">0870 444 3853</Field> <Field name="url">www.museumoflondon.org.uk</Field> <Field name="id">3</Field> <Field name="GeoQuality">4</Field> <Field name="GeocodeDate">2007-05-17</Field> <Field name="GeocodeSource">cp071</Field> </Fields> <Distance> <Miles>0.30</Miles> <KM>0.48</KM> </Distance> <Point> <Lat>51.51778</Lat> <Lon>-0.09656</Lon> </Point> </Record> ... <Record counter="8"> <Fields> <Field name="client_id" /> <Field name="name">Horniman Museum</Field> <Field name="street">100 London Road</Field> <Field name="town">London</Field> <Field name="pc">SE23 3PQ</Field> <Field name="state" /> <Field name="country">GB</Field> <Field name="telephone">020 8699 1872</Field> <Field name="fax">020 8291 5506</Field> <Field name="url">http://www.horniman.ac.uk/</Field> <Field name="id">2</Field> <Field name="GeoQuality">4</Field> <Field name="GeocodeDate">2007-05-17</Field> <Field name="GeocodeSource">cp071</Field> </Fields> <Distance> <Miles>5.49</Miles> <KM>8.84</KM> </Distance> <Point> <Lat>51.44113</Lat> <Lon>-0.06074</Lon> </Point> </Record> </RecordSet> <RecordSet dataSource="[datasource2]" totalRecordCount="998"> <Record counter="1"> <Fields> <Field name="client_id">441</Field> <Field name="name">Dr Johnson's House</Field> <Field name="street">Gough Square</Field> <Field name="town">LONDON</Field> <Field name="pc">EC4A 3DE</Field> <Field name="country">UK</Field> <Field name="telephone">020 7353 3745</Field> <Field name="fax">020 7353 3745</Field> <Field name="url">www.drjh.co.uk</Field> <Field name="locationtype" /> <Field name="id">441</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">531300</Field> <Field name="y">181200</Field> </Fields> <Distance> <Miles>0.29</Miles> <KM>0.46</KM> </Distance> <Point> <Lat>51.51450</Lat> <Lon>-0.10920</Lon> </Point> </Record> ... <Record counter="10"> <Fields> <Field name="client_id">470</Field> <Field name="name">Shakespeare's Globe Exhibition</Field> <Field name="street">New Globe Walk</Field> <Field name="town">LONDON</Field> <Field name="pc">SE1 9DT</Field> <Field name="country">UK</Field> <Field name="telephone">020 7902 1500</Field> <Field name="fax">020 7902 1515</Field> <Field name="url">www.shakespeares-globe.org</Field> <Field name="locationtype" /> <Field name="id">470</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">532200</Field> <Field name="y">180300</Field> </Fields> <Distance> <Miles>0.74</Miles> <KM>1.19</KM> </Distance> <Point> <Lat>51.50620</Lat> <Lon>-0.09650</Lon> </Point> </Record> </RecordSet> </RecordSets>


Example 3

In response to a search with multiple data sources where one search returns a result and the other one does not:

http://clients.multimap.com/API/search/1.2/[api_key]?qs=EC4&count=2&city=London&countryCode=GB
&dataSource=[datasource1],[datasource2]

Response 3

<?xml version="1.0" encoding="UTF-8" ?> 
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="998"> <Record counter="1"> <Fields> <Field name="client_id">441</Field> <Field name="name">Dr Johnson's House</Field> <Field name="street">Gough Square</Field> <Field name="town">LONDON</Field> <Field name="pc">EC4A 3DE</Field> <Field name="country">UK</Field> <Field name="telephone">020 7353 3745</Field> <Field name="fax">020 7353 3745</Field> <Field name="url">www.drjh.co.uk</Field> <Field name="locationtype" /> <Field name="id">441</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">531300</Field> <Field name="y">181200</Field> </Fields> <Distance> <Miles>0.29</Miles> <KM>0.46</KM> </Distance> <Point> <Lat>51.51450</Lat> <Lon>-0.10920</Lon> </Point> </Record> <Record counter="2"> <Fields> <Field name="client_id">445</Field> <Field name="name">The Guildhall</Field> <Field name="street">Guildhall Yard</Field> <Field name="town">LONDON</Field> <Field name="pc">EC2V 5AE</Field> <Field name="country">UK</Field> <Field name="telephone">020 7606 3030</Field> <Field name="fax">020 7260 1119</Field> <Field name="url" /> <Field name="locationtype" /> <Field name="id">445</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">532400</Field> <Field name="y">181300</Field> </Fields> <Distance> <Miles>0.42</Miles> <KM>0.68</KM> </Distance> <Point> <Lat>51.51510</Lat> <Lon>-0.09330</Lon> </Point> </Record> <RecordSet dataSource="[datasource2]" totalRecordCount="0" /> </RecordSets>


Example 4

In response to a search with a specified bounding box, the search returns those records from the data source that are within the bounds of the box:

http://clients.multimap.com/API/search/1.2/[api_key]?bb=-2.30972,52.1238;-1.176,52.16995

Response 4

<?xml version="1.0" encoding="UTF-8" ?> 
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="1"> <Record counter="1"> <Fields> <Field name="client_id">764</Field> <Field name="name">Farnborough Hall</Field> <Field name="street" /> <Field name="town">BANBURY</Field> <Field name="pc">OX17 1DU</Field> <Field name="country">UK</Field> <Field name="telephone">01295 690 202</Field> <Field name="fax" /> <Field name="url" /> <Field name="locationtype" /> <Field name="id">764</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">443000</Field> <Field name="y">249400</Field> </Fields> <Point> <Lat>52.14120</Lat> <Lon>-1.37310</Lon> </Point> </Record> </RecordSet> </RecordSets>


Example 5

In response to a search request with a fieldFilter parameter:

http://clients.multimap.com/API/search/1.2/[api_key]?fieldname_1=client_id&operator_1=eq&value_1=100

Response 5

<?xml version="1.0" encoding="UTF-8" ?> 
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="1"> <Record counter="1"> <Fields> <Field name="client_id">100</Field> <Field name="name">The Lost Gardens of Heligan</Field> <Field name="street" /> <Field name="town">ST. AUSTELL</Field> <Field name="pc">PL26 6EN</Field> <Field name="country">UK</Field> <Field name="telephone">01726 845 100</Field> <Field name="fax">01726 845 101</Field> <Field name="url">www.heligan.com</Field> <Field name="locationtype" /> <Field name="id">100</Field> <Field name="GeoQuality">9</Field> <Field name="GeocodeDate">0000-00-00</Field> <Field name="GeocodeSource" /> <Field name="x">199900</Field> <Field name="y">46400</Field> </Fields> <Point> <Lat>50.28350</Lat> <Lon>-4.81010</Lon> </Point> </Record> </RecordSet> </RecordSets>


Example 6

In response to a request that specified that results be within minDistance and maxDistance parameters and be displayed from the third record onwards (in response to a &minDistance, &maxDistance and &startIndex search request):

http://clients.multimap.com/API/search/1.2/[api_key]?qs=EC4&minDistance=177&maxDistance=580&startIndex=3&city=London
&countryCode=GB

Response 6

<?xml version="1.0" encoding="UTF-8" ?> 
<RecordSets xmlns="http://clients.multimap.com/API" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation
="http://clients.multimap.com/API http://clients.multimap.com/Schema/search_1.2.xsd"> <RecordSet dataSource="[datasource1]" totalRecordCount="4"> <Record counter="3"> <Fields> <Field name="client_id">DE01</Field> <Field name="name">German Museum of Technology Berlin (GMTB)</Field> <Field name="street">Trebbiner Str. 9</Field> <Field name="town">Berlin</Field> <