This page covers several topics that you must know how to do or be familiar with before developing GeoAPI-based applications. In addition, the Sidebar on the right of your screen contains a hyperlinked table of contents for the GeoAPI documentation.
GeoAPI API Key [Top]
Before using GeoAPI for production code, you must fill out the form here to get your own API key. You can either use the same key for all your applications (in which case, watch out for the daily query quota described below) or get a different key for each one. While you can use the demo key, "demo", for testing or demo purposes, do not use it for production code. Since many people are trying out GeoAPI, it's very likely that demo key using apps will be blocked due to daily rate limits.
By default, each key is limited to 20,000 queries per day, where a day is defined as 0000-2359 UTC. If your app is taking off at warp speed and you're getting close to that many queries, email us at "api at geoapi.com" and we can increase your quota. Note that there is a small fee when you run more than 20,000 GeoAPI queries per day; see our price structure here.
As part of the API Key application, you must agree to our Terms of Use. If you rely on us as an important piece of your infrastructure, please be sure you understand what's OK and what isn't. We try to keep the Terms clear and reasonable, including having a plain English version, but if you're not clear on anything in them please email us at "api at geoapi.com".
Trying Out GeoAPI [Top]
To try out or experiment with GeoAPI, you can either use your web browser or a command line http tool such as curl. Remember that curl's URL argument must be in quotes, for example:
curl "http://api.geoapi.com/v1/parents?lat=37.563475&lon=-122.323219&apikey=demo&pretty=1"
You can also download our simple Python API client. Please feel free to contribute a client in your favorite language!
GeoAPI On The iPhone [Top]
For details about how to get and use GeoAPI's SDK for the iPhone, see here.
GeoAPI Key Concepts and Datatypes [Top]
Entities are objects in the world, and can be either physical things (a business, a statue, a park, etc.) or areas with arbitrary boundaries (a neighborhood, a school district, a city, etc.). Search results consist of entities that match the search's parameters. All entities exist in the GeoAPI database and have a webpage that shows their data; for example, http://geoapi.com/e/cafe-valencia-san-francisco-ca-94110. Users cannot modify the content of GeoAPI defined entities.
However, users and applications can add annotations to any entity. See the User Views section for details. You can also create and annotate new entities. See Creating App-Specific Entities for details.
Any user created entities and annotations are kept in a namespace based on the application's API key, so that only apps using that key can access them.
An entity has the following attributes, all of which exist for every entity.
- guid: An entity's unique identifier string. For example, Ritual Roasters in San Francisco, CA has a guid value of ritual-coffee-roasters-san-francisco-ca-94110. In case of effective real world duplication, such as two stores that are both part of the same chain being across the street from each other, additional information such as a street address or number is added to their guids to make them unique. This is a permanent identifier of that business; if a guid changes, it's effectively the same as deleting one entity and creating a new one.
- name: Entity name, a string, for example "Ritual Roasters". A string. Note that while an entity's guid and shorturl values are unique, its name may not be. For example, there are many, many, "Starbucks". Also, an entity can be renamed. For example, if the business entity named "Foundation Bookstore" is sold to someone who renames it "Second Foundation Bookstore", eventually its entity's name value would change, but its guid could stay the same.
- type: Entity type, one of the following six strings. Currently supported types are:
- city: Over 20K US city entries with guids such as "mountain-view-ca".
- neighborhood: US neighborhoods with guids such as "castro-upper-market-san-francisco-ca"
- business: GeoAPI knows about over 16 million US businesses.
- POI: Points of interest such as the Golden Gate Bridge, parks, train stations, etc. One way of thinking about points of interest is that they're real world things at a fixed location that aren't businesses.
- intersection: More than 10 million intersections with guids such as "21st-st-and-valencia-st-san-francisco-ca". If multiple streets intersect, or a street changes names at an intersection (such as North 5th Street turning into South 5th Street), all street names are included; "peachtree-st-and-main-st-and-second-ave-springfield-ga".
- user-entity: All entities created by users or applications, instead of the ones that exist in the GeoAPI database for all GeoAPI users (which are all of the first five types above). See Creating App-Specific Entities.
- geom: Entity geometry as a valid geojson (see http://geojson.org/) object. Can be a single point (a business) or a polygon (a bounded location, such as a park, neighborhood, or city). GeoAPI can use all seven geojson types; Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection WARNING: geojson presents coordinates in the order longitude, latitude to be compatible with the more "natural" Cartesian presentation of x, y.
Entities exist in a location type hierarchy. Given a guid or lat/lon coordinate values, you can request that location's parents' entity values. In both cases, you use a parents method, but with a different url and parameters depending on whether you have a guid or lat/lon values. See Parents Methods.
For example, if you did a parents query on the lat/lon values 37.563475 and -122.323219, it would return a list of the entities with guids downtown-san-mateo-ca and san-mateo-ca. If you did a parents query on the entity with guid ritual-coffee-roasters-san-francisco-ca-94110, it would return a list of the entities with guids mission-san-francisco-ca and san-francisco-ca.
There is an implied parent hierarchy for each entity type value:
- lat/lon_location -> neighborhood -> city
- business -> neighborhood -> city
- POI -> neighborhood -> city
- intersection -> neighborhood -> city
- user-entity -> neighborhood -> city
- neighborhood -> city
However, there is no specific defined hierarchy. A parent is simply defined as an entity that contains the geometry (point or boundaries) of a child entity. So, for example, if you try to find the parents of a city, the result value will be [], the empty list. If a business is located outside of any city or neighborhood boundaries, it will also have no parents. Similarly, a business in a small town may only have a city parent and no neighborhood parent.
Given a particular entity, you can request one of several views of it, where a view consists of additional data associated with that entity or its location. Note that views can only be created for entities; views don't work for lat/lon point locations.
The following views currently exist. We expect to continue to write additional view methods. If there's a view you'd like to see, please submit it to us as a feature request.
- flickr: Available for all entity types, this view method returns an array of JSON object name/value pairs representing public photos on Flickr and their associated metadata. Range is photos taken within 1km of a point entity and from within the boundaries of a polygon entity. See Flickr View.
- foursquare: Available for all entity types, this view method takes an entity's guid and returns an array of JSON object name/value pairs representing Foursquare tips messages and their associated metadata. Range is tips uploaded from a location within 1km of point locations or within the boundaries of a polygon/boundary defined location. See Foursquare View.
- listing: Available only for business entities, this view method consists of properties relevant to businesses, such as opening hours, phone number, type of business, etc. See Listing View.
- twitter: Available for all entity types, this view method returns an array of JSON object name/value pairs representing tweets and their associated metadata. Range is those tweets made within 1km of a point entity and from within the boundaries of a polygon entity. See Twitter View.
- weather: Available for all entity types, this view method returns the current, real time, weather conditions for an entity's location in the continental United States (and soon, most of the world). See Weather View.
- youtube: Available for all entity types, this method returns an array of JSON object name/value pairs representing YouTube videos and their associated metadata. Range is videos uploaded from within 1km of a point entity or within the boundaries of a polygon entity. See YouTube View.
You can also create User Views that allow developers and users to annotate any GeoAPI entity with their own data. This private data is kept in its own namespace which has a one-to-one correspondence with an application's GeoAPI key. Each namespace can contain multiple distinct views, which can only be accessed by users/developers with that GeoAPI key.
