log inhelp

View
 

Simple Search

URL | Parameters | Response Properties | Example | Query | Response

 

The search method takes a latitude/longitude coordinate pair and an optional radius distance. It returns entities within that distance from the location as a JSON array of property-value objects. Entities can only be constrained by type and results are ordered by their distance from the location.

 

URL          [Top]

 

http://api.geoapi.com/v1/search

 

Parameters          [Top]

 

  • lat:
    • Required.
    • Latitude coordinate of search location.
    • Format: Positive or negative floating point number.
  • lon:
    • Required.
    • Longitude coordinate of search location.
    • Format: Positive or negative floating point number.
  • radius:
    • Optional.
    • Maximum distance from search location for results.

    • Format: Floating point number followed by unit abbreviation with no space in-between. For example, 0.1km or .1km. Note that in the actual query (as shown below in the example), this parameter's name is automatically changed to radius-in-meters and its value converted to a floating point number of meters.

  • type:
    • Optional.
    • Only return results of this entity type. Allowed values are business, POI, intersection, neighborhood, city, and user-entity. Only one value is allowed; you can't do an implicit OR by specifying multiple values.
    • Format: String.
  • include-parents:
    • Optional.
    • Description: Includes the parents of the returned entities in results.
    • Format: Set to 1 to include parents. Default is not to include them.
  • limit:
    • Optional.
    • Description: Maximum number of returned results.
    • Format: Positive integer. Default is 10 and maximum is 100. 
  • apikey:
    • Required.
    • The 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]

 

  • distance-in-meters: An integer, distance from the lat/lon parameter coordinates in meters.
  • guid: A string, a returned entity's unique GeoAPI guid.
  • 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, MultiPolygon, 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 compatible with 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, GeoAPI entity type (business, POI, intersection, neighborhood, city, user-entity).
    • name: A string, the entity's name.
    • views: An array of strings of view names.

 

Example          [Top]

 

This method is also used in the Location Check-Ins and Location Annotation of Twitter Streams demos.

 

Query          [Top]

 

http://api.geoapi.com/v1/search?lat=37.75647&lon=-122.421218&radius=0.1km&apikey=demo&pretty=1

 

Response          [Top]

 

{
"query": {
"params": {
"lon": -122.421218, 
"num-results": 10, 
"lat": 37.75647, 
"radius-in-meters": 100, 
"type": "any", 
"include-parents": false
}, 
"type": "search"
}, 
"result": [
{
"distance-in-meters": 0, 
"guid": "ritual-coffee-roasters-san-francisco-ca-94110", 
"meta": {
"geom": {
"type": "Point", 
"coordinates": [
-122.421218, 
37.75647
]
}, 
"guid": "ritual-coffee-roasters-san-francisco-ca-94110", 
"type": "business", 
"name": "Ritual Coffee Roasters", 
"views": [
"listing"
]
}
}, 
{
"distance-in-meters": 7, 
"guid": "nor-cal-refrigeration-san-francisco-ca-94110", 
"meta": {
"geom": {
"type": "Point", 
"coordinates": [
-122.421211, 
37.756405999999998
]
}, 
"guid": "nor-cal-refrigeration-san-francisco-ca-94110", 
"type": "business", 
"name": "Nor Cal Refrigeration", 
"views": [
"listing"
]
}
}, 
...
]
}

 

 

Printable version