The Basic Meeting List Toolbox

Try The New Semantic Workshop!

Parameters for the “switcher=GetSearchResults” Value

NOTE: These are all case-sensitive!

NOTE: There are a number of possible values for each parameter. When we say “array,” we mean that the same parameter is repeated, with an open/close bracket ([]) between it and the values. For example: meeting_ids=123 means search only for one meeting, whose ID is “123”, while meeting_ids[]=123&meeting_ids[]=456 indicates that two meetings are being sought by ID: 123, and 456.

These are possible parameters that you append to the URL described previously. You append these as URL arguments. For example, searching for all meetings that occur on Saturday and Sunday, and returning the results as XML, would look like this:

http://bmlt.newyorkna.org/main_server/client_interface/xml/?switcher=GetSearchResults&weekdays[]=1&weekdays[]=7

The same search, returning a geographic result (KML) would look like this (remember that we don’t specify the

parameter in the geographic searches):

http://bmlt.newyorkna.org/main_server/client_interface/kml/?weekdays[]=1&weekdays[]=7

Geographic Location

We don’t use address lookups. Instead, we geolocate the meetings via the longitude and latitude assigned to each meeting.

NOTE: When you specify a negative integer (NOT floating-point number) as a value for

or

, you are telling the server to select its own radius. The value of the integer indicates roughly how many meetings you want included in the search. The actual number is almost certain to vary from the requested amount, so consider it more of a “ball park” figure.

geo_width

A floating point number. This is the radius (not diameter) of the search, in MILES (not Kilometers). If this is negative, then it should be an integer, and that indicates an auto-radius is requested to find the number of meetings in the integer. This is mutually exclusive with the

geo_width_km

parameter. You can use one, but not both.

geo_width_km

A floating point number. This is the radius (not diameter) of the search, in KILOMETERS (not Miles). If this is negative, then it should be an integer, and that indicates an auto-radius is requested to find the number of meetings in the integer. This is mutually exclusive with the

geo_width

parameter. You can use one, but not both.

long_val

If one of the two radius specifiers (

geo_width

or

geo_width_km

) is set, this is applied. This is a floating point number that specifies the longitude, in degrees, of the center of the search radius.

lat_val

If one of the two radius specifiers (

geo_width

or

geo_width_km

) is set, this is applied. This is a floating point number that specifies the latitude, in degrees, of the center of the search radius.

String Searches

String searches in the BMLT are done “across the board.” The search goes through all of the meeting fields (like address fields and formats, as well as the meeting name). Additionally, we use metaphone for English and Spanish searches (It can be disabled). Metaphone is a “sounds like” algorithm that can help to compensate for misspellings and whatnot. It can, however, interfere with very specific text searches (for example, it will think that “While” and “Wyle” are the same word).

SearchString

A string. If this is specified, then all the string fields of the meetings specified by the above criteria will be searched for the string. By default, if the language supports metaphone (sound like search), then that is used.

SearchStringAll

A boolean (1 or 0). If nonzero, then all of the words in the search string will have to be matched for a meeting to qualify.

You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.

SearchStringExact

A boolean (1 or 0). If nonzero, metaphone will not be used, and the spelling must be exact.

You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.

StringSearchIsAnAddress

A boolean (1 or 0). Nonzero means that the given string should not be checked against any of the fields in the meeting data. Instead, it is to be considered a submission to the Google Maps geocode, and will be used to determine a center point in a local search.

You do not need to specify 0 as a value. Simply not including this parameter is the same as a false value.

SearchStringRadius

A positive floating-point, or negative integer.

If specified, the radius of the search around the address. The units are in whatever the server units are for the Root Server’s server’s native setting (can be miles or kilometers).

Negative numbers must always be integers, and specify a rough target number of meetings for auto-radius. The rules are the same as with the

geo_width

or

geo_width_km

parameters. This is mutually exclusive with the

geo_width

or

geo_width_km

parameters. You can only use one of these parameters at a time.

This parameter is ignored if

StringSearchIsAnAddress

is false.

Weekdays

This parameter specifies which day of the week the meeting starts on.

weekdays

(Can be specified as an array, with more than one value)

This is an array of positive (or negative) integers, from 1 to 7. Each integer represents a weekday (1 -> Sunday, 7 -> Saturday).

A positive integer means that the search will look specifically for meetings that occur on that weekday.

If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t occur on that weekday.

Start Time

The following values specify a start time “window.” The meeting must start on, or after

, and can start no later than

StartsAfterH

A positive integer between 0 and 23. The hour of the minimal start time for meetings, in military time.

StartsAfterM

A positive integer between 0 and 59. The minute of the minimal start time for meetings, in military time.

StartsBeforeH

A positive integer between 0 and 23. The hour of the maximal start time for meetings, in military time.

StartsBeforeM

A positive integer between 0 and 59. The minute of the maximal start time for meetings, in military time.

Meeting Duration

The following values specify a time duration “window.” The meeting can last no longer than

, and no less than

.

MinDurationH

A positive integer. This is the number of hours in the minimal duration.

MinDurationM

A positive integer. This is the number of minutes in the minimal duration.

MaxDurationH

A positive integer. This is the number of hours in the maximal duration.

MaxDurationM

A positive integer. This is the number of minutes in the maximal duration.

Sorting Results

There are a few basic “default” searches available for most searches, but we also have the ability to specify sorts more intricately.

The Default Sorts

sort_key

The keys by which to sort. These are established at the root server. The default keys are:

weekday

This sorts first, by weekday, then by town, then by borough, then by neighborhood, and finally by start time. This is the default.

time

This sorts first, by weekday, then by start time, then by town, then by borough, and finally by neighborhood.

town

This sorts first, by town, then by borough, then by neighborhood, then by weekday, and finally, by start time.

state

This sorts first, by state (province), town, then by borough, then by neighborhood, then by weekday, and finally, by start time.

state_weekday

This sorts first, by weekday, then by state (province), town, then by borough, then by neighborhood, and finally by start time.

sort_dir

This is the direction of the sort. It can be:

asc

Ascending (Default)

desc

Descending

sort_results_by_distance

Specifying this overrides other sort criteria, but it only applies to radius/geographic searches. If specified, then results are sorted by distance from the longitude/latitude provided as the search center. Closest first, most distant, last.

The Specific Sort

sort_keys

This is a comma-separated list of values (not an array).

If this parameter is specified, the

sort_key

and

sort_dir

parameters are both ignored.

Each value is the name of a meeting data field in the database.

NOTE: Not all of these will work in predictable ways! You’ll need to experiment, in order to determine the best parameters. Different Root Servers may behave in different ways, as these rely heavily on the content of the server. Some of these will be downright useless.

The default values available are:

id_bigint

This is the BMLT ID of the meeting

weekday_tinyint

This is the day of the week

start_time

This is the time of day that the meeting begins

duration_time

This is the meeting duration

formats

The list of format codes associated with the meeting

lang_enum

The language used for the meeting

service_body_bigint

The Service body for the meeting (Note: Sorts by Service body ID, not name)

longitude

latitude

The longitude and latitude

worldid_mixed

The NAWS Committee Code

meeting_name

The name of the meeting

location_text

The name of the building/facility in which the meeting gathers

location_info

Any extra information associated with the meeting

location_street

The street address of the meeting

location_city_subsection

The borough (or “Ku,” if you are in Tokyo) of the city

location_neighborhood

The neighborhood of the city (like “Harlem” or “Brookline”)

location_municipality

The name of the town

location_sub_province

The county

location_province

The state or province

location_postal_code_1

The zip code, or postal code

location_nation

The nation

comments

Any comments associated with the meeting

train_lines

Any train line information associated with the meeting

bus_lines

Any bus line information associated with the meeting

desc

If this is supplied, then the search direction will be descending (ascending is default)

Specifying Values for Specific Fields

There is a mechanism to specify a field in the meeting record, and search only for meetings with a specific value in that field. This is done by the use of two parameters:

meeting_key

This specifies which field is to be checked. The possible values are:

meeting_name

The name of the meeting

location_text

The name of the building/facility in which the meeting gathers

location_info

Any extra information associated with the meeting

location_street

The street address of the meeting

location_city_subsection

The borough (or “Ku,” if you are in Tokyo) of the city

location_neighborhood

The neighborhood of the city (like “Harlem” or “Brookline”)

location_municipality

The name of the town

location_sub_province

The county

location_province

The state or province

location_postal_code_1

The zip code, or postal code

location_nation

The nation

comments

Any comments associated with the meeting

train_lines

Any train line information associated with the meeting

bus_lines

Any bus line information associated with the meeting

meeting_key_value

This is the value to match for that meeting key. This can use metaphone for string fields.

meeting_key_match_case

If 1, the case must match. Default is 0. NOTE: Setting this to 1 also stops the metaphone search.

meeting_key_contains

If this is set to 0, then the string must be complete. Default is 1 (contains).

New In Root Server Version 2.5.3: The “simple_other_fields” Parameter

The “Other” fields (customized fields, like Contact Addresses and Train/Bus Lines) are normally sent in a manner that combines their prompt and their value.

The syntax is “<PROMPT>#@-@#<VALUE>“.

If you add “&simple_other_fields=1” to the parameter list, only the value will be returned.

New In Root Server Version 2.8.8: The “Meeting Ends Before” Parameters

Starting with Root Server version 2.8.8, there’s a couple of new parameters that you can add that specify that meetings that meet the search criteria must END before or at a given time.

EndsBeforeH

A positive integer between 0 and 23. The hour of the maximal end time for meetings, in military time.

EndsBeforeM

A positive integer between 0 and 59. The minute of the maximal end time for meetings, in military time.

Service Bodies

You can search for meetings that belong to specific Service bodies. You do this by specifying the Service bodies by their BMLT ID

services

(Can be specified as an array, with more than one value)

This is an array of positive integers. Each integer represents the ID of a Service Body. A positive integer means that the search will look specifically for meetings that contain that Service Body ID. If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t contain that ID. If no ‘services’ values are given, then the search will not use the Service Body field as a search criteria.

Individual Meetings

You can search for meetings by their BMLT ID

meeting_ids

(Can be specified as an array, with more than one value)

This is an array of positive integers. Each integer represents the ID of a meeting. A positive integer means that the search will look specifically for meetings that contain that ID (only 1 result per ID, of course). If the integer is negative (preceded by a minus sign -), then the criteria will be to look for meetings that don’t contain that ID. If no ‘meeting_ids’ values are given, then the search will not use the ID field as a search criteria.

Languages

You can also search for meetings by their language

langs

(Can be specified as an array, with more than one value)

This is an array of 2-character strings. The search will look specifically for meetings that are in the indicated language[s]. If the language is preceded by a minus sign -, then the criteria will be to look for meetings that are not in that language. If no ‘langs’ values are given, then the search will not use the lang_enum field as a search criteria.

Filtering For Only Certain Data Fields

This parameter allows you to specify that only certain fields be returned, as opposed to everything in the meeting record.

NOTE: This does not apply to the geographic searches, which will ignore this parameter. They already know what they need to return.

data_field_key

This is a comma-separated list of values (not an array). Each one is a data field. If they are included in this list, then they will be returned.

The default values available are:

id_bigint

This is the BMLT ID of the meeting

weekday_tinyint

This is the day of the week

start_time

This is the time of day that the meeting begins

duration_time

This is the meeting duration

formats

The list of format codes associated with the meeting

lang_enum

The language used for the meeting

service_body_bigint

The Service body for the meeting (Note: Sorts by Service body ID, not name)

longitude

latitude

The longitude and latitude

worldid_mixed

The NAWS Committee Code

meeting_name

The name of the meeting

location_text

The name of the building/facility in which the meeting gathers

location_info

Any extra information associated with the meeting

location_street

The street address of the meeting

location_city_subsection

The borough (or “Ku,” if you are in Tokyo) of the city

location_neighborhood

The neighborhood of the city (like “Harlem” or “Brookline”)

location_municipality

The name of the town

location_sub_province

The county

location_province

The state or province

location_postal_code_1

The zip code, or postal code

location_nation

The nation

comments

Any comments associated with the meeting

train_lines

Any train line information associated with the meeting

bus_lines

Any bus line information associated with the meeting

Getting the Formats Used In A Search (JSON and XML Only)

The JSON and XML responses have the ability to attach an extra field to the response. This would contain the same format “legend” as returned by the

parameter, but with a key difference: These would only be the formats actually used in the meetings that were returned by the search. The

parameter returns ALL possible formats, including ones that are not used by any meetings.

get_used_formats

This appends a

&lt;formats&gt;

XML element, or a

"formats":

JSON element to the end of the returned search. This will contain the same data as the

switcher=GetFormats

parameter.

get_formats_only

This is the same as above, but it does not include any meeting data; just formats.

In the next page, we’ll cover getting change records semantically.

• Semantic Interfaces
• Using Semantics
• Types of Semantics
• Search Parameters
• Change Parameters
• Example Response Data
• NAWS-Format Dump
• Semantic Administration
• The BMLT Semantic Workshop