Documentation for the Geoconnect API

Overview

The Geoconnect API allows you to access our large collection of organized "districts". There are different levels to each district: Admin0 represents a country, (e.g. "Sudan"). Admin1 is a region within that country(e.g. "Red Sea"). Admin2 is a district within that region (e.g. "Port Sudan"), and Admin3 is a sub-district of that district (e.g. "Al Shargi").

The API returns a JSON object that looks like this:

{ geoconnect_id: 27464, admin0id: 135, admin0: "Sudan", admin1id: 714, admin1: "Red Sea", admin2id: 2309, admin2: "Port Sudan", admin3id: 2025, admin3: "Al Shargi" }

How to access the API

To gain access to our API, simply request a key. Once we receive your request a unique key will be generated and sent to you via email. This key is yours, and you should take care to keep it private. Once you have your key, you can pass it as a URL string query by setting it as the value to the parameter :api_key to begin consuming the API.

.../api/countries?api_key=your_unique_api_key_goes_here

Passing your key as the only URL query, as in the example above, will return active districts from the database. There are more parameters available, and the different URL queries can be chained together to further filter, sort and even control how many results are fetched from the database at a time. Read on to learn more about these functionalities.

Filtering results

Results can be filtered by name according to the different levels discussed in the overview (geoconnect_id, admin0, admin1, admin1_id, admin2, admin2_id, admin3, or admin3_id). To filter, pass one of the levels as a URL string query and set the value of the parameter to the specific name you are looking for. The query is not case-sensitive, however to avoid returning wildcard results spelling must be exact. This filtering string query will follow your api key. Make sure to separate different queries with an & symbol.

.../api/countries?api_key=your_unique_api_key_goes_here&admin0=sudan

Sorting

The results are sorted alphabetically by name according to the highest filtered level. The above example would return districts of Sudan, sorted by their respective admin1 name. To organize by a different level, simply pass the level as the value to the :sort parameter.

.../api/countries?api_key=your_unique_api_key_goes_here&admin0=sudan&sort=admin2

By default, the API returns the results in ascending alphabetical order. To return the results in a descending alphabetical order you can use the :direction parameter with the value set to desc

.../api/countries?api_key=your_unique_api_key_goes_here&admin0=sudan&sort=admin2&direction=desc

Pagination

By default the API will return 50 results from the database at a time per page. 50 results is also the maximum amount of results per page that you can receive at a time, 0 being the least. in order to specify how many results per page pass the :page_size parameter with the value set to the number of results desired as a query string.

.../api/countries?api_key=your_unique_api_key_goes_here&admin0=sudan&sort=admin2&direction=desc&page_size=25

Navigating the pagination is very simple as well. Just set the page number as the value to the :page parameter.

.../api/countries?api_key=your_unique_api_key_goes_here&admin0=sudan&sort=admin2&direction=desc&page_size=25&page=2

GeoJSON

The GeoJSON API provides encoded geographic data for each country in the form of Feature objects commonly used by geospatial applications.

You can request GeoJSON for a single country, set of, or all countries. Please reference a GeoJSON repository to obtain the proper geojson_id needed as a parameter when requesting a single or set of countries. For example, the geojson_id for Kiribati is "KIR".

GET All Countries

.../api/geojson?api_key=__your_unique_api_key_goes_here__

GET Set of Countries

.../api/geojson?api_key=__your_unique_api_key_goes_here__&geojson_ids[]=__geojson_id__&geojson_ids[]=__geojson_id__

GET Single Country

.../api/__geojson_id__/geojson?api_key=your_unique_api_key_goes_here

The successful API request will return an array of GeoJSON Feature object(s) for the requested country or countries that looks like this: [{"type":"Feature","id":"ALB","properties":{"name":"Albania"},"geometry":{"type":"Polygon","coordinates":[[[20.590247,41.855404],[20.463175,41.515089]]]}}]