API v2 - Record Searching
Search for resources using keywords, match terms, geography and various other parameters.POST
{ "Dataset": "on", "Lang": "en", ... }
• A Dataset parameter is required for all requests. Typically the province code but can be different for specialized data sets.
• The Lang parameter is set to either search the English (default: "en") or French ("fr") database. Not all data sets support French.
"fr"
French (not available for all data sets and may not be available for all resources)
"coverage"
Search for resources that serve a specified community or coordinates
["Toronto", "York", "Peel"]
"Toronto|York|Peel"
Multiple communities in array format when using JSON
Multiple communities delimited by vertical line
Communities or latitude/longitude coordinate set are required in coverage searches
"match"
Match searches
"Exact"
"Words"
"ExactWords"
"AI"
"NaturalLanguage"
Exact term must be present
Words must be present (no partial matches)
Exact words/phrase must be present
Uses AI embedding to match query on taxonomy terms for better results
Natural language search (beta)
-- Only operational with Ontario Data Set with MapIDs = on
-- Can only be used with term + proximity searches
-- SortOrder not currently supported
"keywords|keywords"
Multiple terms in array format when using JSON or delimited by a vertical line
"or"
Use a second match where either match is met
"keywords|keywords"
Multiple terms in array format using JSON or delimited by a vertical line |
"distance"
"name"
Sort by distance (coordinates must be used)
Sort alphabetically
false / 0
["English", "French"]
"English|French"
Multiple languages in array format when using JSON
Multiple languages delimited by vertical line |
"and"
Match all of the specified languages
Cannot be used with MinAge and MaxAge
-- Match searches only
"score-high"
Include records but score higher (comes up first with sort by "best"
"off"
Turning this on will retrieve a static id for these resources (Ontario Data Set only).
"AlternateName"
"OfficialName"
"ParentAgency"
"RecordOwner"
"UniqueIDPriorSystem"
"MailingAttentionName"
"MailingAddress1"
"MailingAddress2"
"MailingCity"
"MailingStateProvince"
"MailingPostalCode"
"MailingCountry"
"MailingAddressIsPrivate"
"PhysicalAddress1"
"PhysicalAddress2"
"PhysicalCity"
"PhysicalCounty"
"PhysicalCommunity"
"PhysicalStateProvince"
"PhysicalPostalCode"
"PhysicalCountry"
"PhysicalAddressIsPrivate"
"OtherAddress1"
"OtherAddress2"
"OtherCity"
"OtherCounty"
"OtherStateProvince"
"OtherPostalCode"
"OtherCountry"
"Latitude"
"Longitude"
"HoursOfOperation"
"EmailAddressMain"
"WebsiteAddress"
"AgencyStatus"
"AgencyClassification"
"AgencyDescription"
"AgencyDescription_Site"
"SearchHints"
"CoverageArea"
"CoverageAreaText"
"Eligibility"
"EligibilityAdult"
"EligibilityChild"
"EligibilityFamily"
"EligibilityFemale"
"EligibilityMale"
"EligibilityTeen"
"LicenseAccreditation"
"IRSStatus"
"FEIN"
"YearIncorporated"
"AnnualBudgetTotal"
"LegalStatus"
"SourceOfFunds"
"ExcludeFromWebsite"
"ExcludeFromDirectory"
"DisabilitiesAccess"
"PhysicalLocationDescription"
"BusServiceAccess"
"PublicAccessTransportation"
"PaymentMethods"
"FeeStructureSource"
"ApplicationProcess"
"ResourceInfo"
"DocumentsRequired"
"AvailabilityNumberOfTimes"
"AvailabilityFrequency"
"AvailabilityPeriod"
"ServiceNotAlwaysAvailability"
"CapacityType"
"ServiceCapacity"
"NormalWaitTime"
"TemporaryMessage"
"TemporaryMessageAppears"
"TemporaryMessageExpires"
"EnteredOn"
"UpdatedOn"
"MadeInactiveOn"
"HighlightedResource"
"LanguagesOffered"
"LanguagesOfferedList"
"LastVerifiedOn"
"LastVerifiedByName"
"LastVerifiedByTitle"
"LastVerifiedByPhoneNumber"
"LastVerifiedByEmailAddress"
"LastVerificationApprovedBy"
"AvailableForDirectory"
"AvailableForReferral"
"AvailableForResearch"
"PreferredProvider"
"ConnectsToSiteNum"
"ConnectsToProgramNum"
"LanguageOfRecord"
"CurrentWorkflowStepCode"
"VolunteerOpportunities"
"VolunteerDuties"
"IsLinkOnly"
"ProgramAgencyNamePublic"
"SiteAgencyNamePublic"
"Categories"
"TaxonomyTerm"
"TaxonomyTerms"
"TaxonomyTermsNotDeactivated"
"TaxonomyCodes"
"Coverage"
"Hours"
"Custom_Minimum Age"
"Custom_Maximum Age"
"Custom_Code"
"Custom_SINV"
"Custom_Bed Count"
"Custom_ESDCID"
"Custom_Elig by Family Comp"
"Custom_Elig by Gender"
"Custom_Elig by Target Pop"
"Custom_OF Bed Count"
"Custom_Public Comments"
"Custom_Former Names"
"Custom_Headings"
"Custom_Legal Name"
"Custom_Pub Codes"
"Custom_iCarol-managed record"
"Custom_iCarol-completed Record"
"Custom_Last Updated By"
"Custom_Facebook"
"Custom_Instagram"
"Custom_LinkedIn"
"Custom_Twitter"
"Custom_YouTube"
{ "RecordCount": Number of resources returned from your search, "Records": [ { "id": Resource ID also known as ResourceAgencyNum, "ParentId": The current resource's parent resource ID or agency record ID, "PublicName": The public name of the resource, "Score": Internally calculated score of the resource to your search, "ServiceArea": Array of geographical areas this resource services, "Distance": Distance to your search coordinates, "Description": Description of the resource, "Latitude": Latitude coordinate, "Longitude": Longitude coordinate, "PhysicalAddressStreet1": Physical street address 1, "PhysicalAddressStreet2": Physical street address 2, "PhysicalAddressCity": Physical city, "PhysicalAddressProvince": Physical province code, "PhysicalAddressPostalCode": Physiical postal code, "PhysicalAddressCountry": Physical country, "MailingAttentionName": Mailing attention mame, "MailingAddressStreet1": Mailing address 1, "MailingAddressStreet2": Mailing address 2, "MailingAddressCity": Mailing city, "MailingAddressProvince": Mailing province, "MailingAddressPostalCode": Mailing postal code, "MailingAddressCountry": Mailing country, "PhoneNumbers": Array of phone numbers that include: { "Phone": Phone number, "Name": Phone number name, "Description": Phone number description, "Type": Phone number type } "Website": Web site address, "Email": Email address, "Hours": Hours of operation, "Hours2": Hours of operation supplementary (there are two hours field due to the nature of our source database), "MinAge": Minimum age*, "MaxAge": Maximum age*, "UpdatedOn": Date this record was last updated on, "RecordOwner": The owner and maintainer of this record* } ] }
When searching by keywords, resources are given a score based on various factors (this is subject to change at anytime as we are regularly improving this algorithm). The "best" sortorder uses the score to order records.
- Base score is 50
- Scores are adjusted after the initial query therefore order of results can change when a different PageSize is used
- Score adjustments change based on the TermMatch method
- Score receives a larger increase for match in the PublicName field
- Score receives a moderate increase for match in the AlternateName or TaxonomyTerms field
- Score receives a small increase for match in AgencyDescription field
- Score receives a moderate increase when multiple words are used as search terms and matches partially or completely in the PublicName field
- Score receives a small increase when multiple words are used as search terms and matches verbatim in AgencyDescription field
- Score receives a small increase if the search terms are found multiple times in the AgencyDescription
- Additional scoring adjustments are made when multiple words are used in the search terms depending on how many match in the PublicName field. Scores will be decreased if the ration of search words to found words is less than 50%
- If you were to filter out low scoring records the ideal threshold would be around 40-45
Examples
Search Types
There are four primary search methods available in this API:
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "food bank" }
- SearchType is set to "proximity"
- Latitude, Longitude and Distance must be provided in proximity searches and are numeric values
- Search is set to "term" for keyword searches
- Term is required for keyword searches and is set to "food bank"
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Pharmacies" }
- SearchType is set to "proximity"
- Latitude, Longitude and Distance must be provided in proximity searches and are numeric values
- Search is set to "match" for match searches
- MatchMode is required in match searches and set to "taxterm"
- MatchTerms is required in match searches and set to "Pharmacies"
- MatchMode can be "headings", "category", "pubcodes", "taxcodes", "taxterm", "taxterms", "all" or an iCarol supported field name
- Please consult with your QueryApp contact for best use cases
- "headings", "pubcodes" and "categories" are an internal categorization method
- "taxcodes" corresponds the actual taxonomy codes (TJ-3000.1500; TJ-3000.8500)
- "taxterm" corresponds to taxonomy terms (Comprehensive Information and Referral; 211 Systems;)
- "taxterms" corresponds to taxonomy terms that include the parent term (Organizational/Community/International Services - Information Services - Information and Referral - Comprehensive Information and Referral; )
- Using MatchMode as "all" will find all the resources in the specified search area and the MatchTerms parameter is not required when "all" is used
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Food Bank", "MatchMulti": "and", "MatchMode2": "taxterm", "MatchTerms2": "Food Donation Programs", "Fields": "TaxonomyTerm" }
- MatchMulti can be used to use a second match within your search and is set to either "and" or "or"
- MatchMode2 is the field to search within for the second match
- MatchTerms2 are the terms to search within for the second field, multiple terms can be delimited with a vertical line |
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Latitude": 48.461312, "Longitude": -89.228477, "Search": "term", "Term": "food bank" }
- SearchType is set to "coverage"
- Latitude and Longitude are numeric values
- Distance is optional, if omitted all resources serving the specified coverage area are returned
- Search is set to "term" for keyword searches
- Term is required for keyword searches and is set to "food bank"
- Resources are sorted by score by default (see last example for sorting by distance)
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Communities": "Terrace Bay|Nipigon", "Search": "term", "Term": "food bank" }
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Latitude": 48.461312, "Longitude": -89.228477, "Communities": "Thunder Bay", "Distance": 10, "Search": "term", "Term": "food bank", "SortOrder": "distance" }
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Latitude": 48.461312, "Longitude": -89.228477, "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Pharmacies" }
- SearchType is set to "coverage"
- Latitude and Longitude must be provided in proximity searches and are numeric values
- Distance is optional, if omitted all resources serving the specified coverage area are returned
- Search is set to "match" for match searches
- MatchMode is required in match searches and set to "taxterm"
- MatchTerms is required in match searches and set to "Pharmacies", multiple terms can be delimited by a vertical line | and the API will match resources with any of the terms provided
- MatchMode can be "headings", "category", "pubcodes", "taxcodes", "taxterm", "taxterms", "all" or an iCarol supported field name
- Please consult with your QueryApp contact for best use cases
- "headings", "pubcodes" and "categories" are an internal categorization method
- "taxcodes" corresponds the actual taxonomy codes (TJ-3000.1500; TJ-3000.8500)
- "taxterm" corresponds to taxonomy terms (Comprehensive Information and Referral; 211 Systems;)
- "taxterms" corresponds to taxonomy terms that include the parent term (Organizational/Community/International Services - Information Services - Information and Referral - Comprehensive Information and Referral; )
- In the above example, using MatchMode as "all" will find all the resources in that search area (within 10km of Thunder Bay) and the MatchTerms parameter is not required when "all" is used
- Resources are sorted alphabetically by default (see last example for sorting by distance)
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Communities": "Terrace Bay|Nipigon", "Distance": 10, "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Pharmacies" }
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Latitude": 48.461312, "Longitude": -89.228477, "Communities": "Thunder Bay|Thunder Bay, Unorganized", "Distance": 10, "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Pharmacies", "SortOrder": "distance" }
{ "Dataset": "on", "Lang": "en", "SearchType": "coverage", "Communities": "Thunder Bay", "Search": "match", "MatchMode": "taxterm", "MatchTerms": "Food Bank", "MatchMulti": "and", "MatchMode2": "taxterm", "MatchTerms2": "Food Donation Programs", "Fields": "TaxonomyTerm" }
- MatchMulti can be used to use a second match within your search and is set to either "and" or "or"
- MatchMode2 is the field to search within for the second match
- MatchTerms2 are the terms to search within for the second field, multiple terms can be delimited with a vertical line |
Paging and Sorting Results
By default the first 25 results will be returned sorted by score. The score is assigned based on various factors including keyword position/density, distance and others. You can change the number of results returned (maximum 1000), the page of results and the sorting order.
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "*", "PageIndex": 0, "PageSize": 50 }
- PageIndex starts at 0 for the first page, 1 would be the second page of results and so forth
- PageIndex and PageSize are numeric values
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "*", "PageIndex": 0, "PageSize": 50, "SortOrder": "name" }
- SortOrder parameter can be set to "best" to sort by score (default), "distance" to sort by proximity or "name" to sort alphabetically.
Additional Filters
Various filters are available to provide more specific results and can used in conjuction with any query.
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "food", "Languages": ["French"] }
- Languages are provided in array format
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 25, "Search": "term", "Term": "*", "Languages": ["French", "Spanish"], "LanguageMatch": "and" }
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "Crisis Support", "MinAge": 16, "MaxAge": 19 }
- MinAge and MaxAge are numeric values. Can be used individually or together.
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "term", "Term": "Crisis Support", "Age": 18 }
- Age must be a numeric value. Cannot be used with MinAge and MaxAge
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 100, "Search": "match", "MatchMode": "all", "ExtCategory": "Test" }
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 100, "Search": "match", "MatchMode": "all", "RequirePhysicalAddress": 1 }
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 100, "Search": "match", "MatchMode": "all", "UpdatedOn": "2020-12-01" }
- UpdatedOn must be in the format YYYY-MM-DD
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "match", "MatchMode": "all", "Fields": "UpdatedOn,TaxonomyTerms" }
{ "Dataset": "on", "Lang": "en", "SearchType": "proximity", "Latitude": 48.461312, "Longitude": -89.228477, "Distance": 10, "Search": "match", "MatchMode": "TaxonomyTerm", "MatchTerms": "food bank", "IncludeRecords": "65303538,65303540", "IncludeRecordsMethod": "score-high" }
- IncludeRecords are the resource ids (ResourceAgencyNum) comma separated
- IncludeRecordsMethod can be set to "score-high" or "mix-in" depending on how you want the results to be sorted