Multimap API V1.2 Web Services Documentation - Searching
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.
The Searching web service parameters, their description and values are as follows:
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
bb | This 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 |
count | This parameter specifies the number of records to display per page (20 by defaults). | Integer | No |
countryCode | This 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 code | No |
dataSource | This 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 |
distanceUnits | This parameter specifies the units in which the
maxDistance and minDistance parameters are shown. | 'KM' or 'miles' | No |
format | This 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 |
lat | This parameter specifies the latitude of the search center point. It returns a result which is the center of the spatial search. | Float; -90 to 90 | No |
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 |
logic | This parameter specifies the logic operator to use if more than one field filter is provided ("AND" by default). | 'AND' or 'OR' or comma-separated list | No |
lon | This parameter specifies the longitude of the search center point. It returns a result which is the center of the spatial search. | Float; -180 to 180 | No |
maxDistance | This parameter specifies the maximum distance a record must be from the search point ("KM" by default). | Float | No |
minDistance | This parameter specifies the minimum distance a record must be from the search point ("KM" by default). | Float | No |
orderByFields | This parameter specifies a comma-separated list of field names by which ordering should be applied. | String or comma-separated list | No |
orderByOrder | This 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 values | No |
returnFields | This 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 list | No |
routeModes | This 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 |
startIndex | This parameter specifies the index of the first record to display (starts at and defaults to 1). | Integer | No |
[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 |
|---|---|---|---|
compoundOrder | This parameter specifies the order of operation by which you wish to evaluate your selected database fields. | String; comma-separated list | No |
compoundThreshold | This parameter specifies the number of matching records that must be found before the compound query halts. | Integer | No |
fieldname_[COUNTER] | This parameter specifies the name of the field in the data source on which to filter, such as fieldname_1, fieldname_2.... | String | No |
operator_[COUNTER] | This parameter specifies the operator to be used in the field filter, such as operator_1, operator_2.... | String | No |
preSearchDataSource | This 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. | String | No |
preSearchFilters | This 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. | String | No |
resultSetSize | This 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. | Integer | No |
value_[COUNTER] | This parameter specifies the value used in the field filter search, such as value_1, value_2.... | String | No |
| Parameter | Description | Valid values | Mandatory |
|---|---|---|---|
city | This parameter specifies the city, town or suburb for the input address. The result it returns is the center of the spatial search. | String | No |
postalCode | This parameter specifies the postal code for the input address. The result it returns is the center of the spatial search. | String | No |
qs | This 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. | String | No |
region | This 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. | String | No |
state | This 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. | String | No |
street | This parameter specifies the street, optionally including a building number, for the input address. The result it returns is the center of the spatial search. | String | No |
ZIP | This 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. | String | No |
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 |
|---|---|---|
eq | fieldname_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. |
lt | fieldname_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. |
gt | fieldname_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. |
not | fieldname_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. |
le | fieldname_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. |
ge | fieldname_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. |
in | fieldname_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. |
null | fieldname_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. |
notnull | fieldname_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. |
contains | fieldname_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. |
startswith | fieldname_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. |
endswith | fieldname_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. |
like | fieldname_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".
|
sl | fieldname_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. |
co | fieldname_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. |
com | compound | Please refer to the section on Compound Searching |
regexp | fieldname_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. |
notlike | fieldname_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_sl | fieldname_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. |
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
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>
| 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" | 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"> | 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> | The RecordSet and RecordSets
elements close here. |
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]
<?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>
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]
<?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>
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
<?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>
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
<?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>
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
<?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> <