LOGIN
GET STARTED FOR FREE »
X

API Documentation


We've used our own API to build this entire site, embedded maps on other sites, create an iPhone application, and offer a mobile version.

What could you do with our data, how could you improve upon your services, or target our data for your users?

Getting Started

The API allows you to query the information stored in our databases, and serve it up in the data format of your choice. You can then use it on your own site, for data analysis, custom spreadsheets, Google Earth, custom mapping applications, or your personal RSS home page.

There are 3 levels of usage. Calls are limited by website domain and IP address:
  1. No API Key - Read our documentation on this page and start making calls to our data. 10 calls per day max. This would be for personal use or testing.

  2. Free API Key - Sign up for an API key for use on your site. 100 calls per day max. Use this if you want to put our data on your own website or create a new service based on our data.

  3. Paid API Key - Contact us for pricing for heavy usage. Unlimited calls per day. Cost is based on actual usage. Professional developers or companies with lots of traffic for their site or application will need to pay reasonble fees to cover the costs of their data usage.

Apigee Support

To get started quickly and start browsing our API calls, browse to our Apigee.com API explorer page.


Mashape Support

To get started quickly with our API, use our Mashape.com API page.


Basic Structure

All calls to the API are made through HTTP web requests. The requests take a number of standard query string parameters and return data to you in a format you specify.

For example, to get information about particular map, you would create a call like this:
http://www.yourmapper.com/api/mapinfo.php?id=e8306bb4ec177d952025e7dbbba585f7c74f8091&format=xml
which would return this xml file:
<?xml version="1.0" encoding="UTF-8" ?>
<item 
Name="Crime Reports" 
Description="Crime in metro Louisville, KY since Jan 2003" 
StartCity="Louisville" 
StartState="KY" 
StateName="Kentucky" 
Coverage="Louisville, Kentucky" 
MapperID="1" 
MapperName="schnuerle" 
UpdateFrequency="Monthly" 
UpdatedDate="2009-02-14 04:44:22" 
CreatedDate="11 Mar 2008" 
DateFilter="1" 
StartDate="2003-01-01" 
EndDate="2009-06-01" 
ViewCount="264" 
RatingTotal="" 
RatingCount="" 
UpdatedDays="30" 
DetailLink="" 
Linkpath="crime-reports/crime-in-metro-louisville-ky-since-jan-2003.htm" 
MarkerType="1" 
MinLat="36.458576" 
MinLon="-89.292831" 
MaxLat="39.321075" 
MaxLon="-82.100578">
</item>
The parameter 'id' is the unique ID of the map, and the parameter 'format' is the return data format (in this case, XML).
An API Key is not required, but would increase your number of requests per day.

Output Formats

Depending on the API call, you can specify your output format in one of the following. All marker data is output using the OMG Standard fields.

  • JSON
  • CSV
  • XML
  • HTML
  • RSS
  • GeoRSS
  • KML
  • Popup (for use in your map popups)

Available Requests

Currently there are 5 very powerful API calls that allow you access to all the map data in the site in a variety of standard formats.

Available API requests:
  • Dataset List - datasetlist.php - List of all datasets (maps) available at a particular location, with details.

  • Map Details - mapinfo.php - Details about a particular map.

  • Map Categories - mapcategories.php - The categories of data available for a map.

  • Marker List - markers.php - List of markers on a map closest to a particular point.

  • Marker Info - markerinfo.php - Details about a particular marker in a dataset.



Dataset List

List of all datasets (maps) available at a particular bounding box location. This is your starting point for getting Dataset IDs which are used in the other calls.

The basic concept is to pass in a rectangle of latitude and longitude coordinates, and get a list of all the datasets in the system that have any points within this bounding box. For example, the bounding box could represent a user's current view port on a map.

Path to API call:
http://www.yourmapper.com/api/datasetlist.php

Example (Min Parameters):
http://www.yourmapper.com/api/datasetlist.php

Example (Max Parameters):
http://www.yourmapper.com/api/datasetlist.php?minlat=30&maxlat=40&minlon=-90&maxlon=-70&format=csv&sort=updated&start=1&num=5&search=crime&category=1&details=0

Result Formats, Example Links:
HTML · XML · CSV · JSON · RSS · GeoRSS

Input Parameters:
Parameter Name Type Required? Description
minlat Minimum Latitude float Good Idea The southernmost line in the bounding box of your search. This assumes a request in the north and western hemispheres, ie, the United States.
maxlat Maximum Latitude float Good Idea The northernmost line in the bounding box of your search.
minlon Minimum Longitude float Good Idea The westernmost line in the bounding box of your search.
maxlon Maximum Longitude float Good Idea The easternmost line in the bounding box of your search.
format Result Format enum: html, mobile, csv, json, rss Good Idea The format of the results. Default is html.
sort Sorting enum: name, updated, rating, views, type, location Good Idea How your results will be sorted, in ascending order. Default is 'location'.
start Start Record integer Optional The first record in your result set. This is useful when you create pagination. Default is 0.
num Number of Records integer Optional The maximum number of results to return. Default is 30.
search Search Term string Optional Will search the datasets' Name and Description for a match.
category Category ID integer Optional The category of datasets you'd like to see. You can pick one of the following: 1=Resturant, 2=Crime, 3=Sex Offender, 4=Real Estate, 5=Historic, 6=Traffic, 7=News, 8=Events, 9=Miscellaneous, 10=Politics, 11=Environment. Leave empty for all categories.
details Show Details boolean Optional If set to 1, the query will provide all available details about each dataset (see the Details column in the results below). This is slightly slower due to query speed and the amount of data returned. If set to 0, it will be just some minimal details, useful for quick queries. Default is 0.

Output Results:
Result Name Type Details Required? Description
ID Dataset ID string Minimal Required Unique Hash ID of the dataset. This will identify the dataset in all relevant API calls and permalinks.
Name Name string Minimal Required Name of the dataset.
Description Description string Minimal Optional Description of the dataset.
Coverage Coverage Area string Minimal Optional Area the dataset covers. It will be national, state, or city and state. If empty, the dataset has global coverage.
MarkerType Marker Type enum: 1, 2 Minimal Required Type of icons/markers used for the dataset. The type represents the size of the icon. 1 = 13x20 pixels. 2 = 13x13 pixels. Used for supplying exact icon size for some type of map applications.
TypeName Country Coverage string Minimal Optional Nation the dataset covers. If empty, the dataset has global coverage.
UpdatedDate Last Updated date time Minimal Required The date the dataset was last updated by the owner.
DaysUpdate Days Since Update integer Minimal Required The number of days since the dataset was last updated.
ViewCount View Count integer Minimal Required The total number of times the map's data has been viewed in any format (site, API, mobile, etc).
RatingScore Rating Score float Minimal Required The current rating of this map, from 0.0 to 5.0. This value is only updated occasionally (a few times a day) so there may be a difference between the returned result and the rating on the site.
StartCity Start City string Full Optional City the dataset starts in. If empty, the dataset has state, national, or global coverage, or it's not specified.
StartState Start State string Full Optional State the dataset starts in. If empty, the dataset has national, or global coverage, or it's not specified.
StateName Coverage State string Full Optional The full name of the state that the dataset covers, if applicable.
MapperID Mapper ID integer Full Required The unique ID of the Mapper who loaded and maintains this data. Used for linking to the mapper's profile.
MapperName Mapper Username string Full Required The unique username of the Mapper who loaded and maintains this data. Used for linking to the mapper's profile.
UpdateFrequency Update Frequency enum: Daily, Weekly, Bi-Weekly, Monthly, Bi-Monthly, Quarterly, Semi-Annually, Annually Full Optional Shows how often the dataset is expected to be updated by the user.
DateCreated Create Date date Full Required The date that the dataset was first made public.
DateFilter Date Filter boolean Full Required Is there a date parameter part of the dataset: 1 = yes, 2 = no. If yes, the startdate and enddate will be provided. The date applies to each individual marker in the dataset.
StartDate Start Date date Full Optional The start date of the data in the dataset, if applicable. Format yyyy-mm-dd.
EndDate End Date date Full Optional The end date of the data in the dataset, if applicable. Format yyyy-mm-dd.
Detaillink Detail Link string Full Optional If it exists, this will be an http link to an external site. It will include the text '[ExternalID]' which should be replaced with an individual marker's ExternalID field. If it is empty, then the data does not link to an external data page.
Linkpath Permalink Path string Full Required Final part of the permalink path to the dataset on Your Mapper. The first part will depend on whether you'd like to link to the full or mobile site. The full site link would be 'http://www.yourmapper.com/map/' + id + '/' + linkpath where 'linkpath' is this field, and 'id' is the datasetid. Mobile link coming soon. You can also append query string parameters to the link.
MinLat Minimum Latitude float Full Required The southernmost line in the bounding box of all the points in this dataset. This assumes a request in the north and western hemispheres, ie, the United States.
MinLon Minimum Longitude float Full Required The westernmost line in the bounding box of all the points in this dataset.
MaxLat Maximum Latitude float Full Required The northernmost line in the bounding box of all the points in this dataset.
MaxLon Maximum Longitude float Full Required The easternmost line in the bounding box of all the points in this dataset.



Map Details

Details about a particular map. After you know the unique ID of a map (dataset), you can get more detailed information about it.

Path to API call:
http://www.yourmapper.com/api/mapinfo.php

Example (Min Parameters):
http://www.yourmapper.com/api/mapinfo.php?id=e8306bb4ec177d952025e7dbbba585f7c74f8091

Example (Max Parameters):
http://www.yourmapper.com/api/mapinfo.php?id=e8306bb4ec177d952025e7dbbba585f7c74f8091&format=xml

Result Formats, Example Links:
HTML · XML · CSV · JSON

Input Parameters:
Parameter Name Type Required? Description
id Dataset ID string Required Unique ID of the dataset. You can get this from the Dataset List API call.
format Data Format enum: html, xml, csv, json Optional Output format of the results. Default is html.

Output Results:
Result Name Type Required? Description
name Dataset Name string Required Name of the Datasets, short and sweet.
description Dataset Description string Optional Longer description of the dataset, a sentence or two.
startcity City Starting Point string Optional Starting city that lies at the center of the map, if applicable.
startstate State Starting Point string Optional Starting state that lies at the center of the map, if applicable.
statename Coverage State string Optional Shows a state name if the dataset has coverage in just one state. Not too useful. If empty it means national coverage. See the coverage field for better info.
coverage Coverage Area string Required An english string that shows the coverage area. Can be 'City, State,' 'State,' or 'National.'
mapperid Mapper ID integer Required The unique ID of the Mapper who loaded and maintains this data. Used for linking to the mapper's profile.
mappername Mapper Username string Required The unique username of the Mapper who loaded and maintains this data. Used for linking to the mapper's profile.
updatefrequency Update Frequency enum: Daily, Weekly, Bi-Weekly, Monthly, Bi-Monthly, Quarterly, Semi-Annually, Annually Optional Shows how often the dataset is expected to be updated by the user.
updateddate Updated Date date time Required The date and time that the data was last updated.
createddate Create Date date Required The date that the dataset was first made public.
datefilter Date Filter boolean Required Is there a date parameter part of the dataset: 1 = yes, 2 = no. If yes, the startdate and enddate will be provided. The date applies to each individual marker in the dataset.
startdate Start Date date Optional The start date of the data in the dataset, if applicable. Format yyyy-mm-dd.
enddate End Date date Optional The end date of the data in the dataset, if applicable. Format yyyy-mm-dd.
viewcount View Count integer Required The total number of times the map's data has been viewed in any format (site, API, mobile, etc).
ratingtotal Rating Total float Optional The current rating of the dataset, from 0 to 5.
ratingcount Rating Count integer Optional The number of individual users who have rated the dataset.
updateddays Days Since Update integer Required The number of days since the last data update.
detaillink Detail Link string Optional If it exists, this will be an http link to an external site. It will include the text '[ExternalID]' which should be replaced with an individual marker's ExternalID field. If it is empty, then the data does not link to an external data page.
linkpath Permalink Path string Required Final part of the permalink path to the dataset on Your Mapper. The first part will depend on whether you'd like to link to the full or mobile site. The full site link would be 'http://www.yourmapper.com/map/' + id + '/' + linkpath where 'linkpath' is this field, and 'id' is the datasetid. Mobile link coming soon. You can also append query string parameters to the link.
markertype Marker Type enum: 1, 2 Required Type of icons/markers used for the dataset. The type represents the size of the icon. 1 = 13x20 pixels. 2 = 13x13 pixels. Used for supplying exact icon size for some type of map applications.
minlat Minimum Latitude float Required The southernmost line in the bounding box of all the points in this dataset. This assumes a request in the north and western hemispheres, ie, the United States.
minlon Minimum Longitude float Required The westernmost line in the bounding box of all the points in this dataset.
maxlat Maximum Latitude float Required The northernmost line in the bounding box of all the points in this dataset.
maxlon Maximum Longitude float Required The easternmost line in the bounding box of all the points in this dataset.



Map Categories

The categories of data available for a map.

Path to API call:
http://www.yourmapper.com/api/mapcategories.php

Example (Min Parameters):
http://www.yourmapper.com/api/mapcategories.php?id=e8306bb4ec177d952025e7dbbba585f7c74f8091

Example (Max Parameters):
http://www.yourmapper.com/api/mapcategories.php?id=e8306bb4ec177d952025e7dbbba585f7c74f8091&format=xml

Result Formats, Example Links:
HTML · XML · CSV · JSON

Input Parameters:
Parameter Name Type Required? Description
id Dataset ID string Required Unique ID of the dataset. You can get this from the Dataset List API call.
format Data Format enum: html, xml, csv, json Optional Output format of the results. Default is html.

Output Results:
Result Name Type Required? Description
icon Icon Path string Required The path to the image icon. It will be in the format /marker/imagename.png, so you'll need to append the domain to it like this: http://www.yourmapper.com/marker/imagename.png.
name Category Name string Required The textual name of the category.
id Category ID integer Required The ID of the category that the map data uses. This ID is returned in the Marker List API call.



Marker List

List of markers on a map closest to a particular point.

Path to API call:
http://www.yourmapper.com/api/markers.php

Example (Min Parameters):
http://www.yourmapper.com/api/markers.php?id=3526d29b0d20ea9860f65324d248829cebf7374e&lat=38.23925875585244&lon=-85.72271347045898

Example (Max Parameters):
http://www.yourmapper.com/api/markers.php?id=3526d29b0d20ea9860f65324d248829cebf7374e&lat=38.23925875585244&lon=-85.72271347045898&c=2,3,&search=c&start=2008-01-01&end=2008-08-01&num=25&f=xml

Note About the Center Marker: this is one special marker that is returned as the first item in the result set. It is located at the center of your request and contains information about the map itself. It has the ID 0.

Result Formats, Example Links:
KML · XML (XOMGL) · CSV · JSON · GeoRSS · RSS 2
KML Format: Note that the KML data format does not return all individual outputs listed below. The format outpus most of the data in one field, the HTML formatted 'description' field, perfect for map popups.

Input Parameters:
Parameter Name Type Required? Description
id Dataset ID string Required Unique ID of the dataset. You can get this from the Dataset List API call.
lat Latitude float Required Latitude coordinate for the middle of your search.
lon Longitude float Required Longitude coordinate for the middle of your search.
f Format enum: kml, xml, csv, rss, geo Optional The format of the results. XML is more specifically in the XOMGL format. RSS is RSS 2.0, so it has geographic coordinates. GEO is GeoRSS. KML is the default if none is provided.
c Categories integer list Optional Comma separated list of category IDs to limit your results.
search Search Keywords string Optional Keyword(s) to filter your results. The location Name and Description fields are searched for an exact string match.
start Start Date date Optional The start date range for your results. This is only used if the dataset supports dates. The format must be yyyy-mm-dd.
end End Date date Optional The end date range for your results. This is only used if the dataset supports dates. The format must be yyyy-mm-dd.
num Number integer Optional The number of results to return, from 1 to 100. The default is 25.

Output Results:
Result Name Type Required? Description
ID Marker ID string Required The unique identifier of the marker/location as provided in the dataset source.
Name Name string Required Short description of the location.
Description Description html Required More detailed, HTML formatted description of the location. It is formatted to fit in a map marker popup window but can be displayed on a web page. Can contain links, markup, and even images.
Category Category integer Required The category ID of the location. The ID is from the list of categories for this dataset.
Location Location string Optional A textual description of the location, or the location search string to be used in place of Address, City, and State.
Address Street Address string Required The street address of the location. This could be a number and a street, a street only, an intersection, or a landmark.
Address2 Address Line 2 string Optional The second part of an address, like unit number or more details about the location.
City City string Required The city of the location.
State State string Required The state of the location.
Zip Zip Code string Optional The zip/postal code of the location.
Date Marker Date date Optional If the dataset has dates, this is the date of the event at this location.
Latitude Latitude float Required The exact latitude of the location.
Longitude Longitude float Required The exact longitude of the location.
URL Extra URL url Optional An optional full http link to an different external page associated with this marker or dataset. This will not be on the Your Mapper site. Note this is different than the DetailLink and Permalink.
ImagePath HTTP Image Path url Optional An optional full http link to an image associated with this marker. It can be any size, but it will be shrunk to fit into the map popups.
DetailLink HTTP External Detail Link url Optional An optional full http link to an external page associated with this specific marker. This will not be on the Your Mapper site. Note this is different than the Permalink and URL fields.
Permalink Permalink url Required Full http permalink path to the page on the Your Mapper site that is dedicated to this location.
Distance Distance float Required The distance in miles, as the bird flies, from the center point of your search to this marker location.



Marker Info

Details about a particular marker in a dataset.

Path to API call:
http://www.yourmapper.com/api/markerinfo.php

Example (Min Parameters):
http://www.yourmapper.com/api/markerinfo.php?set=111&id=29933

Example (Max Parameters):
http://www.yourmapper.com/api/markerinfo.php?set=111&id=29933&format=html

Result Formats, Example Links:
HTML · XML · CSV · JSON · Popup

Input Parameters:
Parameter Name Type Required? Description
id Marker ID string Required Unique id of the marker. It is the ExternalID result from the Marker List API call.
set Dataset ID integer Required Unique ID of the dataset. You can get this from the Dataset List API call.
format Data Format enum: html, xml, csv, json Optional Output format of the results. Default is html.

Output Results:
Result Name Type Required? Description
ExternalID Marker External ID string Required The unique identifier for a marker in a dataset. It is the string that the dataset owner uses to identify the specific marker. It could be any combination of numbers, letters and dashes.
Name Marker Name string Required Descriptive name of the location.
Description Marker Description html Optional Any combination of text and html that describes the locations. The end result will only be large enough to fit into a map marker popup window.
Date Marker Date date Optional If the dataset has dates, this is the date of the event at this location.
ImagePath HTTP Image Path url Optional An optional full http link to an image associated with this marker. It can be any size, but it will be shrunk to fit into the map popups.
DetailLink HTTP External Detail Link url Optional An optional full http link to an external page associated with this marker. This will not be on the Your Mapper site. Note this is different than the Permalink field.
LastUpdated Last Updated date time Required The date and time this location was last updated.
Address Street Address string Required The street address of the location. This could be a number and a street, a street only, an intersection, or a landmark.
Address2 Address Line 2 string Optional The second part of an address, like unit number or more details about the location.
City City string Required The city of the location.
State State string Required The state of the location.
Zip Zip Code string Optional The zip/postal code of the location.
Latitude Latitude float Required The exact latitude of the location.
Longitude Longitude float Required The exact longitude of the location.
Category Category Name string Required The map category of this location.
CatID Category ID integer Required The unique category ID of this location.
CatImage Category Image Name string Required The file name of the category image. Use it in image path in place of 'imagename' as seen in this link: http://www.yourmapper.com/marker/imagename.png
CatColor Category Color hex Required The 6-digit hex value for the color assocaited with this category.
Details Extra Details html Optional Any sort of extra information about this location. Can include basic HTML tags and formatting.
Permalink Permalink url Required Full http permalink path to the page on the Your Mapper site that is dedicated to this location.

Error Codes

If you specify invalid parameters, exceed your daily free API usages, or leave out required parameters, you may get one of the following error messages. All messages come back in the data format you requested.

Code Types

Format: 3 Digit Error Code, Error Name, Optional Details

3 Digit Codes:
None - everything is fine
100 - General
200 - Formatting
300 - Timed Out
400 - No Data
500 - Protected
600 - Over Limit
700 - Not Allowed
800 - Database Issue
900 - Deleted

Format: CSV

500,Protected,Dataset is Protected

Format: JSON

{ "Error" 
{ "Code": "500", 
"Name": "Protected", 
"Message": "Dataset is Protected"
} 
}

Format: XML

‹xml version="1.0" encoding="UTF-8"?›
‹error Code="500" Name="Protected" Message="Dataset is Protected" /›

Format: RSS

‹?xml version="1.0" encoding="utf-8"?›
‹rss version="2.0"›
‹channel›
‹title›500‹/title›
‹description›Error: Protected - Dataset is Protected‹/description›
‹/channel›
‹/rss›

Format: GEO

‹?xml version="1.0" encoding="UTF-8"?›
‹feed›
‹title›500‹/title›
‹subtitle›Error: Protected - Dataset is Protected‹/subtitle›
‹/feed›

Format: KML

‹?xml version="1.0" encoding="utf-8"?›
‹kml›
‹Document›
‹name›500‹/name›
‹description›Error: Protected - Dataset is Protected‹/description›
‹/Document›
‹/kml›

Format: HTML

Error: 500. Protected - Dataset is Protected.

API Key

Your API Key is visible on your account home page.
You are not logged in, giving you 10 views per day free.
Login to have an API key automatically be added to your widget code to increase your usage limits to 100 per day.
By using your free account's API Key with your API calls, you:
  1. Increase your daily usage limits
  2. Consolidate all your Widget Maps and API Calls into one account
  3. Consolidate your API Key tracking across multiple websites/domains
  4. Access usage reports and charts on daily, monthly, and yearly usage per domain
  5. Block API Key usage on any domain you don't own
Users not using an API key will be able to make 10 requests to the API per day. If you sign up for a key and add the key to your requests (with &key=########## attached to your queries) then you can query the API 100 times per day. If you need more requests than that, then you will have to contact us for heavy usage pricing.

 
Quantcast