NAME

Acme::Free::Public::APIs - Perl API client for FreePublicAPI.com's API for for listing APIs.

This module provides the client, "freeapis", that is available via PATH after install.

SYNOPSIS

#!/usr/bin/env perl

use strict;
use warnings;

use Acme::Free::Public::APIs qw//;

my $api     = Acme::Free::Public::APIs->new->random;
my $out     = <<EOAPI;
id:            %d
title:         %s%s
site URL:      %s
methods:       %s
health:        %d
documentation: %s
description:   %s
EOAPI
printf $out, $api->id, ($api->emoji) ? sprintf("(%s) ",$api->emoji) : "",, $api->title, $api->source, $api->methods, $api->health, $api->documentation, $api->source;

freeapis Commandline Client

After installing this module, simply run the command freeapis without any arguments, and it will print information regarding a randomly selected free API that is listed on its site. Below you may see a project familiar to some in the Perl community, the https://world.openfoodfacts.org/ Project.

shell> freeapis
id:            174
title:         (🍲) OpenFoodFacts
site URL:      https://freepublicapis.com/openfoodfacts
methods:       1
health:        84
documentation: https://world.openfoodfacts.org/data
description:   Open Food Facts is a food products database made by everyone, for everyone. You can use it to make better food choices, and as it is open data, anyone can re-use it for any purpose.
shell>

DESCRIPTION

This is the Perl API for the Dog API, profiled at https://www.freepublicapis.com/api.

Contributed as part of the FreePublicPerlAPIs Project described at, https://github.com/oodler577/FreePublicPerlAPIs.

This fun module is to demonstrate how to use Util::H2O::More and Dispatch::Fu to make creating easily make API SaaS modules and clients in a clean and idiomatic way. These kind of APIs tracked at https://www.freepublicapis.com/ are really nice for fun and practice because they don't require dealing with API keys in the vast majority of cases.

This module is the first one written using Util::H2O::More's HTTPTiny2h2o method that looks for JSON in the content key returned via HTTP::Tiny's response HASH.

METHODS

new

Instantiates object reference. No parameters are accepted.

apis( [id => INT] )

Requires no parameters, but may be passed the named parameter id.

When called without any parameters, caller will get an ARRAY reference list of all APIs currently being reported as working.

When passed a specific API id, the returned ARRAY reference contains just the requested API HASH..

See the freeapis client's apis subcommand for an example of what can be done with the output of this method.

random

Accepts no parameters. Returns full HASH of information on a random API. See the freeapis client's random subcommand to see an example of what can be done with the output.

freeapis OPTIONS

apis [--id INT] [--details]

If called without the option --id parameter, this returns a full list sorted by id in ascending order. Optional parameter, --details, will dump all the information available for each API.

 shell> freeapi apis | sort -k2 -r -n | less # sorting on column #2
 319   80 Monster Hunter World API
 320   95 World Wonders
 321  100 Church Calendar API
 322   95 Motivational API
 323   95 Buddha Quotes API
 324   95 Fortnite API
 325   95 Dragon Ball API
 326   95 Demon Slayer API
 327   90 Jojo's Bizarre API
Found 300 APIs

Naturally, it can be used with the commandline to sort on other fields such as health, e.g.:

shell> freeapi apis | sort -k2 -r -n | less # sorting on column #2
321  100 Church Calendar API
191  100 IP Geolocation & Currency Converter
129  100 IP Geolocation API
 92   99 French Address API
 94   95 Carbon Intensity API
 90   95 JSONPlaceholder
 88   95 Stadt Land Fluss
 80   95 Dungeons and Dragons
 77   95 Digimon API
 75   95 Rick and Morty API
 72   95 kanye.rest
 71   95 Coinpaprika API
 70   95 Met Museum Collection
 68   95 Data USA
 62   95 Harry Potter API
 54   95 Star Wars API
 53   95 Nationalize API
 51   95 The Cat API
 48   95 Open Brewery DB
 47   95 Fruityvice
 46   95 Useless Facts API
 45   95 Corporate Bullshit Generator
 44   95 Virenmonitoring API
 36   95 Open Meteo
 35   95 CoinGecko API
 34   95 Agify.io
326   95 Demon Slayer API
...
shell>

Similarly, some clever commandline antics will allow one to do specific queries by id (first column) when piped to other commands.

When --id is specified, it outputs just the corresponding line for the referened API.

shell>freeapi apis --id 321
321  100 Church Calendar API

When --details is added, it shows the full amount of information:

shell>freeapi apis --id 321 --details
id:            321
title:         (📅) Church Calendar API
site URL:      https://freepublicapis.com/church-calendar-api
methods:       2
health:        100
documentation: http://calapi.inadiutorium.cz/api-doc
description:   The Church Calendar API provides access to calendar data for any day, allowing users to retrieve various liturgical celebrations and details. It supports multiple languages and enables specific queries for feast names and calendar descriptions based on the selected calendar system.
Found 1 API

random

This subcommand takes no arguments. When run it prints out to STDOUT all the information provided for it.

shell>
id:            320
title:         (🌍) World Wonders
site URL:      https://freepublicapis.com/world-wonders
methods:       2
health:        95
documentation: https://www.world-wonders-api.org/v0/docs
description:   Free and open source API providing information about world wonders
shell>

Internal Methods

There are no internal methods to speak of.

ENVIRONMENT

Nothing special required.

AUTHOR

Brett Estrade <oodler@cpan.org>

BUGS

Please report.

LICENSE AND COPYRIGHT

Same as Perl/perl.