API Documentation

Every data source we have listed has a corresponding REST API endpoint to "GET" information from it. Below is the usage documentation for all of our data sources.

Contents

Getting Started

Our API for each data source are REST endoints. Only GET is enabled as these data sources are all read only. Currently there is no authentication required to use these APIs, though they are rate limited. By using our index to find the data source you need, click on the "API" section to find the URL where you can access the API for each data source.

Example Endpoint

Below is the link for a very simple continent names data source. If you click on the link, it will return all the data in JSON format.

https://api.dedolist.com/api/v1/locations/continent-codes/

That is the simplest way you can retrieve data via the API. That basic option is available for most data sources unless the source is too large to return in one call.

Find

Find is one of the actions you can use to query each endpoint. Find will simply return the first item that matches the criteria you pass in. You can pass in multiple fields with a value to match. If the data matches all of the fields passed in, then it will return that item. Simply add "find" to the end of the URL and in the query parameters add the field name and value you want to match.

Let's look at an example. Say you want to find the telephone area code for "Jersey City". You would request form your URL like the following:

https://api.dedolist.com/api/v1/locations/continent-codes/find?city=Jersey City

Again if you click through on that you will see only the record for "Jersey City" being returned. You can see in the url we added "find" action and we passed the field name of "city" and passed a value to match of "Jersey City". You can also send multiple fields to query as well as in this example.

https://api.dedolist.com/api/v1/business/area-codes-usa/find?city=Newark&state=Ohio

Filter

Filter is one of the actions you can use to change what information is returned with each endpoint. Filter returns all records that match criteria you pass in. You can pass in multiple fields with a value to match. If the data matches all of the fields passed in, then it will return that item. Let's look at an example. Say you want to find all the postal codes for a city in Canada. You would create a URL like the following:

https://api.dedolist.com/api/v1/business/postal-codes-canada/filter?city=Calgary

As you can see in the example above you can easily filter the data and return just want you need. Just as in the "find" action, you can pass multiple fields to match for a filter.

https://api.dedolist.com/api/v1/business/postal-codes-canada/filter?city=Barrie&province-code=ON

Paging

Sometimes the data returned is too large to be returned all at once. You can pass a "limit" and optionally an "offset" value to any endpoint to page through the results. Here is another example using the time zones API.

First Page of 25 items: https://api.dedolist.com/api/v1/locations/all-utc-timezones/?limit=25&offset=0

Second Page of 25 items: https://api.dedolist.com/api/v1/locations/all-utc-timezones/?limit=25&offset=25

You can of course using paging with the "filter" action as well. There are no limits on page sizes you can use, although there are limits on how much data can be returned at one time. For every API call you can find the total amount of records in the response header in a property called "x-total-count". You can use the total to determine how many "pages" you might need to return the whole data set.

Sorting

For every API you can also pass in a "sort" value to sort the data by any field you desire. Here is an example with the Periodic Table API sorting the list by "phase" in ascending order.

https://api.dedolist.com/api/v1/science/periodic-table-summary/?sort=phase

You can sort on multiple fields by separating them with a comma as well as pass in an additional modifier to sort by ascending(asc) or descending(desc) order. Here is another example.

https://api.dedolist.com/api/v1/science/periodic-table-summary/?sort=phase,name:desc

Operators

Operators are available to make more advanced "filter" or "find" calls. Operators can optionally be added to the beginning of the search value in order to make a search comparison. Ex. `altitude=GT:4000` All operators MUST be in capitals in order to be recognized. Here is an example to our Star Wars locations API that will return any location to the Star Wars universe introduced on or after the year 2000 but not in films.

https://api.dedolist.com/api/v1/entertainment/star-wars-fictional-locations/filter?year=GTE:2000&media=NE:film

Here is a list of all the operators you can use:

More Information

There is currently no authentication required to access these APIs. They are FREE FOR ALL. We may introduce optional authentication in the future for extra customization. We do however have a rate limit in place. You cannot make more than 20 calls per minute. In the response headers you can see how many you have left before it resets. If you find an issue with the API, please open an issue on the Dedolist open-data github.