Introduction | URL | Parameters | GeoAPI Queries | Field Explanation | Constraining Properties In Search Results | Requesting Properties In Search Results | Examples |
Search Limited By Business Type And Only Some Properties Returned | Query | Response |
Search Limited By Business Type With All Properties Returned | Query | Response |
All Views For An Entity With Results Constrained By Name | Query | Response
Introduction to MQL Search Concepts
In addition to Simple Search and Keyword Search, you can also search for entities using MQL, the Metaweb Query Language. This more powerful search lets you specify constraints on entity property values, including values contained in views.
For an MQL search, you provide a query that's similar in form to a response. The property values given in the query do one of two things:
- Control what entities are returned from the search: If a query property has a specific value, say "foo" : x, then the search only returns entities whose foo property also has the value x.
- Control what property values are included in search results: If a query property has the value null, that property's value is returned for any entities matching the search query and constraints.
For example, if you wanted to return the names and prices of all menu-items of type dessert, your query would include the following:
{
"menu_item": [{
"name": null,
"price": null,
"type": "dessert"
}]
}
Any menu-item properties other than name, price, and type will not be included in the search results.
If you're not already familiar with MQL, we suggest looking at the MQL Reference Guide and MQL Cheat Sheet.
http://api.geoapi.com/v1/q
Parameters [Top]
- q:
- apikey:
- Required.
- Your GeoAPI key.
- Format: String.
- pretty:
- Optional.
- Enables easier to read prettified JSON in result.
- Format: Set equal to 1 to enable prettification.
- jsoncallback:
- Optional.
- Return response in JSONP format. JQuery has nice support for JSONP callbacks.
- Format: JSON prefix string.
GeoAPI Queries [Top]
Geo search queries follow this pattern:
{
"lat": <lat>,
"lon": <lon>,
"radius": <radius>,
"limit": <limit>,
"entity": [{
<entity_property_1>,
<entity_property_2>,
...,
"view.<view_name>": {
<view_property_1>,
<view_property_2>,
...
}
}]
}
Field Explanation [Top]
- lat:
- Required.
- Latitude point coordinate value.
- Format: Positive or negative floating point number.
- lon:
- Required.
- Longitude point coordinate value.
- Format: Positive or negative floating point number.
- radius:
- Required.
- Maximum distance from point coordinates from which search results are returned.
- Format: Floating point number followed by unit abbreviation (ex. 0.1km or .1km). See Search Methods for a list of supported units. The default radius is 500m and the maximum radius is 1km (2km if you constrain type to POI).
- limit:
- Optional.
- Maximum number of returned results.
- Format: Positive integer. Default value is 10 and maximum value is 100.
- <entity_property>:
- Optional.
- A query can have any number of entity properties. Specifying a value for a property constrains the search results to only return entities with that property value. Specifying a null value causes the property and its value to be returned in the search results.
- Format: The full list of properties is listed at the GeoAPI root url of an entity (http://geoapi.com/e/), as specified by its guid, for example, http://geoapi.com/e/ritual-coffee-roasters-san-francisco-ca-94110).
- <view_name>:
- Optional.
- Allows the query to filter results based on properties defined in the view. You may specify multiple views in a single query.
- Format: String. Must be either listing or the name of a user view of the form "view.listing". If <view_name>: null, the search returns results for that view without any constraints.
- <view_property>:
- Optional.
- A query can have any number of view properties. Specifying a value for a property constrains the search results to only return entities with that property value. Specifying a null value causes the property and its value to be returned in the search results.
- Format: Valid property names for the specified view. For example, for the listing view, the possible properties can be seen on the view results for an entity (ex. http://api.geoapi.com/v1/e/ritual-coffee-roasters-san-francisco-ca-94110/view/listing)
Constraining Properties [Top]
You constrain a property (i.e. filter by a specific value) by specifying the property and the value to filter it by. Supported MQL constraint operators are:
- equality - MQL doc
- "name": "Tartine" name is required to be equal to "Tartine".
- inequality ("but not" operator) - MQL doc
- "name!=": "Tartine" name can be anything but "Tartine" (including null).
- less than - MQL doc
- "score<": 6 score can only be less than 6.
- greater than - MQL doc
- "score>": 6 score can only be greater than 6.
- prefix - MQL doc
- "name^=": "The" name is required to start with "The".
- Note that our syntax here is slightly different than regular MQL. Instead of having a regex operator, we have an explicit prefix operator (^).
WARNING!
You can constrain results only based on indexed properties. Currently, these are:
- view.listing/name
- view.listing/verticals
- view.listing/features
- view.listing/web-wide-rating
Requesting Properties In Search Results [Top]
As shown above, specifying a property name and the null value in a query causes that individual property to be included in search results. You can also request that all properties of an entity or view be included in the results by passing in a wildcard.
- property to request - MQL doc
- "name": null Fill in the name property in the response.
- wildcards MQL doc
- "*": null Return all properties.
You can experiment with different queries using our handy query tool (which is also a demo) located at http://api.geoapi.com/demos/mql_tool/query.html.
MQL Search is also used in the What's Near Me demo.
The three examples below only show the q parameter part of a query, and that in MQL form rather than in url format. So here's an example of what an MQL query translated into a full GeoAPI search url looks like:
Note that spaces, quotes, colons, brackets, etc. must be converted into URL format.
Radius Search With Results Limited By Type Of Business And Only Some Properties [Top]
This search only returns businesses that are both restaurants and coffee houses. For those businesses, it only returns their name and address property values.
{
"lat": 37.75629
"lon": -122.4213
"radius": "0.2km"
"entity": [{
"guid": null
"type": "business"
"view.listing": {
"a:verticals": "restaurants"
"b:verticals": "food-and-drink:coffee-houses"
"address": []
"name": null
}
}]
}
{
"lat":37.75629,
"lon":-122.4213,
"radius":"0.2km",
"entity":[{
"view.listing":{
"address":["1026 Valencia St",
"San Francisco",
"94110"
],
"name":"Ritual Coffee Roasters",
"b:verticals":"food-and-drink:coffee-houses",
"a:verticals":"restaurants"
},
"guid":"ritual-coffee-roasters-san-francisco-ca-94110",
"type":"business"
},
{
"view.listing":{
"address":["968 Valencia St",
"San Francisco",
"94110"
],
"name":"The Creek Cafe",
"b:verticals":"food-and-drink:coffee-houses",
"a:verticals":"restaurants"
},
"guid":"the-creek-cafe-san-francisco-ca-94110",
"type":"business"
},
{
"view.listing":{
"address":["1109 Valencia St",
"San Francisco",
"94110"
],
"name":"Cafe Valencia",
"b:verticals":"food-and-drink:coffee-houses",
"a:verticals":"restaurants"
},
"guid":"cafe-valencia-san-francisco-ca-94110",
"type":"business"
},
{
"view.listing":{
"address":["3248 22nd St",
"San Francisco",
"94110"
],
"name":"Revolution Cafe",
"b:verticals":"food-and-drink:coffee-houses",
"a:verticals":"restaurants"
},
"guid":"revolution-cafe-san-francisco-ca-94110",
"type":"business"
},
{
"view.listing":{
"address":["3239 22nd St",
"San Francisco",
"94110"
],
"name":"La Altena Market & Cafe",
"b:verticals":"food-and-drink:coffee-houses",
"a:verticals":"restaurants"
},
"guid":"la-altena-market-and-cafe-san-francisco-ca-94110",
"type":"business"
}
]
}
Radius Search With Results Limited By Type Of Business With All Properties Returned [Top]
{
"lat": 37.75629
"lon": -122.4213
"radius": "0.2km"
"entity": [{
"guid": null
"type": "business"
"view.listing": {
"a:verticals": "restaurants"
"b:verticals": "food-and-drink:coffee-houses"
"*": null
}
}]
}
{
"lat":37.75629,
"lon":-122.4213,
"radius":"0.2km",
"entity":[{
"view.listing":{
"hours":[["Mon to Fri",
"6:00am to 10:00pm",
""
],
["Sat",
"7:00am to 10:00pm",
""
],
["Sun",
"7:00am to 9:00pm",
""
]
],
"web-wide-rating":4,
"features":["Credit Card OK",
"Price: Cheap"
],
"chain":null,
"address":["1026 Valencia St",
"San Francisco",
"94110"
],
"canonical-url":"http://www.townme.com/ritual-coffee-roasters-san-francisco-ca-94110",
"verticals":["food-and-drink:coffee-houses",
"restaurants"
],
"phone":"(415) 641-1024",
"a:verticals":"restaurants",
"b:verticals":"food-and-drink:coffee-houses",
"sips":["soy latte",
"espresso",
"hipsters",
"blue bottle",
"mission",
"coffee shop",
"baristas",
"cappuccino",
"outlets",
"foam"
],
"listing-url":"http://www.ritualroasters.com",
"name":"Ritual Coffee Roasters"
},
"guid":"ritual-coffee-roasters-san-francisco-ca-94110",
"type":"business"
},
{
"view.listing":{
"hours":null,
"web-wide-rating":3.5,
"features":["Credit Card OK",
"Outdoor Seating",
"Price: Cheap"
],
"chain":null,
"address":["968 Valencia St",
"San Francisco",
"94110"
],
"canonical-url":"http://www.townme.com/the-creek-cafe-san-francisco-ca-94110",
"verticals":["food-and-drink:coffee-houses",
"restaurants"
],
"phone":"(415) 641-0888",
"a:verticals":"restaurants",
"b:verticals":"food-and-drink:coffee-houses",
"sips":["ritual",
"power outlets",
"laptop",
"free wifi",
"bagel",
"mission",
"wireless",
"study",
"coffee shop",
"plugs"
],
"listing-url":null,
"name":"The Creek Cafe"
},
"guid":"the-creek-cafe-san-francisco-ca-94110",
"type":"business"
},
...
All Views For An Entity With Results Constrained By Name [Top]
Remember, lat/lon parameters are required, even if you specify a guid.
{
"lat": 37.75629
"lon": -122.4213
"radius": "0.2km"
"entity": [{
"*": null
"type": "business"
"view.listing": {
"name": "Ritual Coffee Roasters"
}
}]
}
{
"lat":37.75629,
"lon":-122.4213,
"radius":"0.2km",
"entity":[{
"bearing-from-center":"65.5081",
"view.listing":{
"hours":[["Mon to Fri",
"6:00am to 10:00pm",
""
],
["Sat",
"7:00am to 10:00pm",
""
],
["Sun",
"7:00am to 9:00pm",
""
]
],
"web-wide-rating":4,
"features":["Credit Card OK",
"Price: Cheap"
],
"chain":null,
"address":["1026 Valencia St",
"San Francisco",
"94110"
],
"canonical-url":"http://www.townme.com/ritual-coffee-roasters-san-francisco-ca-94110",
"verticals":["food-and-drink:coffee-houses",
"restaurants"
],
"phone":"(415) 641-1024",
"sips":["soy latte",
"espresso",
"hipsters",
"blue bottle",
"mission",
"coffee shop",
"baristas",
"cappuccino",
"outlets",
"foam"
],
"listing-url":"http://www.ritualroasters.com",
"name":"Ritual Coffee Roasters"
},
"distance-from-center":"21m",
"name":"Ritual Coffee Roasters",
"views":["twitter",
"listing"
],
"geom":{
"type":"Point",
"coordinates":[-122.421218,
37.75647
]
},
"view.twitter":[{
"iso_language_code":"en",
"text":"We have a new art exhibit @ dolores! Opening party tomorrow. bring your friends. Come early for happy hour and... http://bit.ly/m5nBR",
"created_at":"Thu, 12 Nov 2009 18:16:22 +0000",
"profile_image_url":"http://a3.twimg.com/profile_images/369921759/dpc_normal.jpg",
"source":"<a href="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" _fcksavedurl="http://www.facebook.com/twitter" rel="nofollow">Facebook</a>",
"location":"iPhone: 37.761433,-122.425705",
"from_user":"DoloresParkCafe",
"from_user_id":22849005,
"to_user_id":null,
"geo":null,
"id":5655576595
},
...
],
"guid":"ritual-coffee-roasters-san-francisco-ca-94110",
"type":"business"
}
]
}
