api.maponics.com logo

Documentation > Methods

Public Methods

Public Methods in the Maponics Spatial API are broken down into four broad categories:

  1. Methods which return attributes of spatial objects. These methods begin with the prefix getGeoAtt.
  2. Methods which return an ID of a single spatial object. These methods begin with the prefix getGeoID.
  3. Methods which return a list of IDS for multiple spatial objects. These methods begin with the prefix getGeoList.
  4. Methods which return geographic coordinates of spatial object. These methods begin with the prefix getGeoPoly.

Click on the name of each method to view the detailed documentation for that method, including sample request and response XML.

Method Description
getGeoAttByArea This request requires you to submit uniquely identifying characteristics for an object within a specific (primary) dataset, and a target (secondary) dataset. the API will spatially determine the list of objects within the secondary dataset that are wholly or partially within the uniquely identified object from the primary dataset, and return a list of attributes for those objects. You may also specify which type of spatial search is performed (INTERSECT/WITHIN). The method defaults to WITHIN.
getGeoAttByAttribute Global catch-all method that allows you to submit a set of parameters that will uniquely identify a geographic area, a set of parameters to be returned, and a dataset to be targetted. The API will make a best-guess attempt to determine which geographic area fulfills the criteria laid out and return the requested attributes for objects in the target dataset within that geographic area. Due to the flexibility of this method, very few parameters are required. However, if ambiguous details are given that do not uniquely identify a single geographic area, the API will simply use the first area that matches. (For example, to return all ZIP Codes in Adams County, Nebraska, you would need to specific both Adams as the target Counry and Nebraska as the target state. Specifying only Adams County (without a state) would cause the API to randomly choose one of the 12 counties called Adams in the US and then return the ZIP Codes within that Adams county, which may or may not be the one you wanted.)
getGeoAttByCity This request requires you to submit a city and two-letter State abbreviation. The API will return a list of attributes for all objects of the selected type within that city/state.
getGeoAttByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the object that those coordinates are within, and then return the desired list of attributes for that object.
getGeoAttByGeom This request requires you to submit a latitude and longitude coordinate pairs for the bottom left and top right of a rectangular area. The API will spatially determine the number of objects that are wholly or partially within that area and return a list of attributes for those objects. You may also specify which type of spatial search is performed (INTERSECT/WITHIN). The method defaults to WITHIN..
getGeoAttByID This request requires you to submit an object id and field list. The API will return the list of attributes for that object.
getGeoAttByName This request requires you to submit an object name, field list and other uniquely identifying features. The API will return a list of attributes for that object.
getGeoAttByRadius This request requires you to submit a latitude and longitude coordinate pair, field list, and a radius in miles. The API will spatially determine the number of objects that are wholly or partially within that radius and return a list of attributes for those objects.
getGeoAttByState This request requires you to submit a two-letter State abbreviation. The API will return a list of attributes for all objects of the selected type within that state.
getGeoFallbackByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will atttempt to determine if the given location is within a neighborhood. If so, it will return the neighborhood name, the city and the state within which that neighborhood resides. The API will search for valid neighborhoods in this order: Neighborhood, Macro Neighborhood, Sub Neighborhood. If the point does not reside within a neighborhood, the API will attempt to locate the census Place within which the point is located. If the point does not reside within a US Census defined Place, the API will return the MCD within which the point is located.
getGeoIDByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the object that those coordinates are within, and return its ID.
getGeoIDByName This request requires you to submit an object name and other uniquely identifying features. The API will return the id for that object.
getGeoListByCity This request requires you to submit a city and two-letter State abbreviation. The API will return a list of IDs for all objects of the selected type within that city/state.
getGeoListByGeom This request requires you to submit a latitude and longitude coordinate pairs for the bottom left and top right of a rectangular area. The API will spatially determine the number of objects that are wholly or partially within that area and return their IDs.
getGeoListByRadius This request requires you to submit a latitude and longitude coordinate pair, and a radius in miles. The API will spatially determine the number of objects that are wholly or partially within that radius and return their IDs.
getGeoListByState This request requires you to submit a two-letter State abbreviation. The API will return a list of IDs for all objects of the selected type within that state.
getGeoNameByCity This request requires you to submit a city and two-letter State abbreviation. The API will return a list of names for all objects of the selected type within that city/state.
getGeoNameByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the object that those coordinates are within, and then return the name of that object.
getGeoNameByID This request requires you to submit an object id. The API will return the name of that object.
getGeoNameByRadius This request requires you to submit a latitude and longitude coordinate pair, field list, and a radius in miles. The API will spatially determine the number of objects that are wholly or partially within that radius and return a list of names for those objects.
getGeoNameByState This request requires you to submit a two-letter State abbreviation. The API will return a list of names for all objects of the selected type within that state.
getGeoNearestByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the ZIP Code that those coordinates reside within and provide attribute data for the nearest ZIP+4 centroid within that ZIP Code to the supplied coordinate.
getGeoPolyByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the object that those coordinates are within, and return the geometry for that object.
getGeoPolyByID This request requires you to submit an object id. The API will return the geometry for that object.
getGeoPolyByName This request requires you to submit an object name and other uniquely identifying features. The API will return the geometry for that object.
getGeoSurroundByCoord This request requires you to submit a latitude and longitude point. The API will determine which object that point falls within (if any) and then return all objects within the target dataset that are contiguous with your identified object.
getGeoSurroundByID This request requires you to submit an object id. The API will return all objects within the target dataset that are contiguous with your identified object.
getGeoSurroundByName This request requires you to submit the name, city and state of a unqiue object. The API will return all objects within the target dataset that are contiguous with your identified object.
getSchoolByCoord This request requires you to submit a latitude and longitude coordinate pair. The API will spatially determine the school attendance zones that those coordinates are within, and then return those attendance zone IDs along with the NCES District ID and District Name, the NCES School ID and School Name, and the education level of the school, for each attendance zone returned.

Note: This method uses the special dataset code of 'SCH' to instruct the API to return cross-dataset data about the school attendance zone and district.
getUsageByDate This method requires you to submit a from date and a to date, both in the format mm/dd/yyyy. It then calculates your API usage between the specific dates and emails that usage to you as a comma-separated values (csv) file. Please note, due to the potential overhead in calculating historical usage, the API does not return data immediately when this method is called. The usage data is calculated in a background process and sent as an email to the email address on your API account.

This method does not require a dataset, and cannot be batched with any other methods
getUsageThisPeriod This method does not require any parameters and simply returns your usage count of the API for the last day, week and month. It also returns the total usage of the API from the start of your account.

This method does not require a dataset, and cannot be batched with any other methods. This method also requires no parameters.

Batch Methods

As was briefly described in the main documentation introductory page, the Maponics Spatial API supports multiple <request></request> sections within a single XML request.

Example Batch request:

<?xml version="1.0" encoding="UTF-8" ?> <data> <auth> <loginname>your_username</loginname> <key>your_api_key</key> </auth> <request> <dataset>N</dataset> <method>getGeoPolyByID</method> <parameters> <id>142</id> <submatch>N</submatch> </parameters> </request> <request> <dataset>N</dataset> <method>getGeoAttByID</method> <parameters> <id>71</id> <fields>place,neighborhd,state</fields> <submatch>N</submatch> </parameters> </request> </data>

The response for this request will include two <response></response> sections, one for each <request></request> section, in the same order as the request sections were provided.

Sample Reponse:

<?xml version="1.0" encoding="UTF-8" ?> <data> <request> <item> <geom>SRID=4326;MULTIPOLYGON(((-88.123669 30.55242, -88.12413 30.556877,-88.13473 30.573558,-88.138026 30.578445,-88.141513 30.576458,-88.152158 30.576555,-88.15539 30.566751,-88.162301 30.560227,-88.165553 30.554744,-88.134837 30.554702,-88.123669 30.55242)))</geom> </item> </request> <request> <item> <place>Birmingham</place> <neighborhd>Fairview</neighborhd> <state>AL</state> </item> </request> </data>

As can be seen, the initial <request></request> section was a getGeoPolyById request, which returns polygonal coordinates for the object specified by the ID. Thus, the first <response></response> section is the one with the coordinates.