log inhelp

View
 

Keyword Search

URL | Parameters | Response Properties | Examples | Global Scope Query | Response | City/Entity Scope Query | Response

 

The keyword-search method searches for businesses by name, rather than by lat/lon location. For example, let's say you want to search for "Ritual" in San Francisco, CA, and you don't have any latitude/longitude values to work from. 

 

For most uses, Keyword Search is a two-step process as it has both a global scope version and an entity scope version:

 

  1. Use global scope to get the guid of the city in which you want to search. Global scope keyword search maps city-state strings to a city entity.
  2. Use entity scope to search within the scope/boundaries of an entity argument for contained entities by name. So, given a city guid, entity scope searches within that city's boundaries for entities whose name matches the query argument. 

 

At the moment, there are limitations on what you can use Keyword Search for:

 

  • In global scope, you can only search for city names.
  • In entity scope, you can only search for business type entities, and then only for businesses' name and verticals property values.

 

URL          [Top]

 

Global Scope: http://api.geoapi.com/v1/keyword-search/

Entity Scope: http://api.geoapi.com/v1/e/<guid>/keyword-search/

 

Parameters          [Top]

 

Note: The parameters for global scope and entity scope are the same.

 

  • q:
    • Required.
    • The string you're searching for. Note that when searching for a city entity, this value should include both city and state; after all, there're a lot of Springfields out there. :)
    • Format: String. If your query contains spaces, you must change them to be %20.
  • limit:
    • Optional.
    • Maximum number of returned results.
    • Format: Positive integer. Default is 10 and maximum is 100.
  • include-parents:
    • Optional.
    • Includes the parents of the returned entities in results.
    • Format: Set to 1 to include parents. Default is not to include them.
  • type:
    • Optional.
    • Constrain results to only be of this entity type.
    • Format: String. For global scope, it can be either none, any, or city, with a default value of any. For entity scope, it can be either none, any, or business, with a default value of any.
  • apikey:
    • Required.
    • Your application's 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.

 

Response Properties          [Top]

 

  • guid: A string, unique GeoAPI guid for the returned entity.
  • meta: Metadata about the entity, returned in its own JSON object with the following properties:
    • geom: Data about the geometry of the entity, returned in its own JSON object with the following properties:
      • type: A string, the entity's geometry as a valid geojson object. Can be a single point or a polygon (a bounded location, such as a park). Can be one of seven types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolyg, and GeometryCollection.
      • coordinates: An array of the entity's longitude and latitude floating point number values in that order (geojson does this rather than lat,lon to be like the more "natural" cartesian x, y order)
    • guid: A string, the entity's unique GeoAPI guid. Yes, this is the same value as the above guid response property.
    • type: A string, any GeoAPI entity type (business, POI, intersection, neighborhood, city, user-entity)
    • name: A string, the entity's name.
    • views: An array of strings of views 

 

Examples          [Top]

 

First, we use global scope to get the guid for the city of San Francisco.

 

Query          [Top]

 

http://api.geoapi.com/v1/keyword-search?apikey=demo&pretty=1&q=San%20Francisco,%20CA

 

Response          [Top]

 

This response does not show the (very long) list of coordinates that make up San Francisco's boundary.

 

{
"query": {
"type": "keyword-search",
"params": {
"type": "city",
"num-results": 1,
"include-parents": false
}
},
"result": [
{
"guid": "san-francisco-ca",
"meta": {
"name": "San Francisco",
"type": "city"
...
}
}
]
}

 

Query          [Top]

 

Now, we use the guid for San Francisco, CA in a entity scope keyword search query that returns businesses in San Francisco, CA whose name contains the string "Ritual" .

 

http://api.geoapi.com/v1/e/san-francisco-ca/keyword-search?apikey=demo&pretty=1&q=Ritual

 

Response          [Top]

 

{
"query": {
"type": "keyword-search",
"params": {
"type": "business",
"num-results": 2,
"include-parents": false
}
},
"result": [
{
"guid": "ritual-coffee-roasters-san-francisco-ca-94110",
"meta": {
"name": "Ritual Coffee Roasters",
"type": "business"
...
}
},
{
"guid": "ritual-coffee-roasters-san-francisco-ca-94124",
"meta": {
"name": "Ritual Coffee Roasters",
"type": "business"
}
}
]
}

 

 

 

Printable version