{"id":17974709,"url":"https://github.com/meeb/ipnetdb-service","last_synced_at":"2025-07-28T08:34:31.575Z","repository":{"id":50369681,"uuid":"442049044","full_name":"meeb/ipnetdb-service","owner":"meeb","description":"Containerised microservice to provide an HTTP JSON API for IPNetDB databases","archived":false,"fork":false,"pushed_at":"2024-07-07T06:30:02.000Z","size":31,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-20T12:51:35.114Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meeb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["meeb"]}},"created_at":"2021-12-27T04:26:11.000Z","updated_at":"2024-07-07T06:30:05.000Z","dependencies_parsed_at":"2024-07-07T07:53:39.204Z","dependency_job_id":null,"html_url":"https://github.com/meeb/ipnetdb-service","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meeb%2Fipnetdb-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meeb%2Fipnetdb-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meeb%2Fipnetdb-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meeb%2Fipnetdb-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meeb","download_url":"https://codeload.github.com/meeb/ipnetdb-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245480551,"owners_count":20622334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-29T17:15:16.860Z","updated_at":"2025-03-25T14:32:14.073Z","avatar_url":"https://github.com/meeb.png","language":"Python","funding_links":["https://github.com/sponsors/meeb"],"categories":[],"sub_categories":[],"readme":"# ipnetdb-service\n\nContainerised microservice to provide an HTTP JSON API for IPNetDB databases.\n\nThis service is designed to be built as a container and deployed in a\ncontainerised application stack or with container orchestration such as with\ndocker-compose or kubernetes. It provides an HTTP-based JSON API to query\n[IPNetDB](https://IPNetDB.com/) network information databases from\nhttps://ipnetdb.com/\n\n**NOTE:** [IPNetDB](https://IPNetDB.com/) databases are free for open source\nuse but they are not free for commercial or closed source use. Please make sure\nyou read the licence on https://ipnetdb.com/ to make sure you are compliant\nbefore using this container! You may need to pay for a licence or add\nattribution to your project.\n\nThe [IPNetDB](https://IPNetDB.com/) databases are not bundled with this\ncontainer. They are downloaded directly from [IPNetDB](https://IPNetDB.com/).\n\n\n## Installation\n\nYou can either build this container yourself:\n\n```bash\n$ make container\n```\n\nOr you can pull a tagged container image directly from here:\n\n```\nghcr.io/meeb/ipnetdb-service:v0.1.1\n```\n\n\n## Running\n\nIPNetDB-Service has no configurable environment variables. The container only\nopens an HTTP server on TCP port 80. You can run it via docker with:\n\n```bash\n$ docker run --rm --name ipnetdb-service -p 80:80 ghcr.io/meeb/ipnetdb-service:v0.1.1\n```\n\nOr for example in a compose stack:\n\n```yaml\n  ipnetdb-service:\n    image: ghcr.io/meeb/ipnetdb-service:v0.1.1\n    container_name: ipnetdb-service\n    restart: unless-stopped\n    ports:\n      - 80:80\n```\n\nIPNetDB-Service is suitable to be used with multiple replicas and in Kubernetes\nor other container orchestration clusters.\n\n\n## Behaviour\n\nOn start the IPNetDB-Service container will download the latest IPNetDB\ndatabases from https://ipnetdb.com/ . This may take a minute or two and the\nservice will not be available until this start-up task is complete.\n\nAt a random time every Monday the IPNetDB databases will be automatically\nupdated and reloaded. The container should be self-maintaining and require\nno operations time to maintain other than monitoring the healthcheck.\n\nThe embedded API server is built on nginx with OpenResty and is capable of\nvery high throughput.\n\n\n## Usage\n\nThe HTTP API has 4 endpoints, listed below. If you query any other URL,\nincluding the `/` root resource, you will see a help page with a\n`404/Not Found` status code.\n\n\n### GET `/healthcheck`\n\nPerforms a healthcheck on the container and returns a `{\"health\": \"ok\"}`\nalong with a `200/OK` status code if the container is healthy. Any other\nresponse means the container is not healthy.\n\n```bash\n$ curl -s http://ipnetdb-service/healthcheck | jq\n{\n  \"health\": \"ok\"\n}\n```\n\n\n### GET `/index`\n\nReturns the currently loaded IPNetDB database index in JSON format. This\nresponse is identical to the JSON file at https://ipnetdb.com/latest.json\nand can be used to determine if the databases currently loaded in the\ncontainer are up to date. Returns either a `200/OK` response if an index\nis available or a `404/Not Found` if no index is loaded.\n\n```bash\n$ curl -s http://ipnetdb-service/index | jq      \n{\n  \"prefix\": {\n    \"url\": \"https://cdn.ipnetdb.net/ipnetdb_prefix_latest.mmdb\",\n    \"file\": \"ipnetdb_prefix_latest.mmdb\",\n    \"date\": \"2021-12-26\",\n    \"sha256\": \"4f740044b16336c07127a124470da4f1fec57586b8bbece952ca85d3d9e78bea\",\n    \"bytes\": 127849480\n  },\n  \"asn\": {\n    \"url\": \"https://cdn.ipnetdb.net/ipnetdb_asn_latest.mmdb\",\n    \"file\": \"ipnetdb_asn_latest.mmdb\",\n    \"date\": \"2021-12-26\",\n    \"sha256\": \"7659820d2eba672f6b9bc553eccf638690c5ca6cfb1ca12ac254349d893f171f\",\n    \"bytes\": 27796664\n  }\n}\n```\n\n\n### GET `/ip/[any IPv4 or IPv6 address]`\n\nFetches information on an any IPv4 or IPv6 address. Returns either a `200/OK`\nstatus and information on the IP address or a `404/Not Fouind` status if the IP\nhas no information in the database. Response is always in JSON. The following\nfields are always returned:\n\n`query`: The IP address that was queried\n`type`: The type of query issued, set to the string \"ip\" for IP queries\n`status`: Either \"found\" or \"not found\"\n`result`: A JSON object of the results of the query if found\n\nSee https://ipnetdb.com/ for more details on the result fields returned.\n\n```bash\n$ curl -s http://ipnetdb-service/ip/1.1.1.1 | jq\n{\n  \"result\": {\n    \"allocation\": \"1.1.1.0/24\",\n    \"allocation_cc\": \"AU\",\n    \"allocation_registry\": \"apnic\",\n    \"allocation_status\": \"assigned\",\n    \"as\": 13335,\n    \"as_cc\": \"US\",\n    \"as_entity\": \"Cloudflare, Inc.\",\n    \"as_name\": \"CLOUDFLARENET\",\n    \"as_private\": false,\n    \"as_registry\": \"arin\",\n    \"prefix_asset\": {},\n    \"prefix_assignment\": \"assigned portable\",\n    \"prefix_bogon\": false,\n    \"prefix_entity\": \"APNIC and Cloudflare DNS Resolver project\",\n    \"prefix_name\": \"APNIC-LABS\",\n    \"prefix_origins\": [\n      13335\n    ],\n    \"prefix_registry\": \"apnic\",\n    \"prefix\": \"1.1.1.0/24\"\n  },\n  \"query\": \"1.1.1.1\",\n  \"status\": \"found\",\n  \"type\": \"ip\"\n}\n```\n\nAn example query for an IPv6 address:\n\n```bash\n$ curl -s http://localhost/ip/2001:4860:4860::8888 | jq\n{\n  \"result\": {\n    \"allocation\": \"2001:4860::/32\",\n    \"allocation_cc\": \"US\",\n    \"allocation_registry\": \"arin\",\n    \"allocation_status\": \"allocated\",\n    \"as\": 15169,\n    \"as_cc\": \"US\",\n    \"as_entity\": \"Google LLC\",\n    \"as_name\": \"GOOGLE\",\n    \"as_private\": false,\n    \"as_registry\": \"arin\",\n    \"prefix_asset\": {},\n    \"prefix_assignment\": \"\",\n    \"prefix_bogon\": false,\n    \"prefix_entity\": \"\",\n    \"prefix_name\": \"\",\n    \"prefix_origins\": [\n      15169\n    ],\n    \"prefix_registry\": \"\",\n    \"prefix\": \"2001:4860::/32\"\n  },\n  \"query\": \"2001:4860:4860::8888\",\n  \"status\": \"found\",\n  \"type\": \"ip\"\n}\n```\n\n\nAn example query to an IP address not in the databases:\n\n```bash\n$ curl -s http://ipnetdb-service/ip/0.0.0.0 | jq\n{\n  \"result\": {},\n  \"query\": \"0.0.0.0\",\n  \"status\": \"not found\",\n  \"type\": \"ip\"\n}\n```\n\n\n### GET `/as/[any AS number]`\n\nFetches information on an any autonomous systems number. Returns either a\n`200/OK` status and information on the ASN or a `404/Not Fouind` status if the\nASN has no information in the database. Response is always in JSON. The\nfollowing fields are always returned:\n\n`query`: The ASN that was queried\n`type`: The type of query issued, set to the string \"as\" for ASN queries\n`status`: Either \"found\" or \"not found\"\n`result`: A JSON object of the results of the query if found\n\nSee https://ipnetdb.com/ for more details on the result fields returned.\n\n```bash\n$ curl -s http://ipnetdb-service/as/12345 | jq  \n{\n  \"result\": {\n    \"name\": \"AS12345\",\n    \"cc\": \"IT\",\n    \"entity\": \"General Software s.r.l.\",\n    \"in_use\": true,\n    \"ipv4_prefixes\": [\n      \"212.47.32.0/19\"\n    ],\n    \"as\": 12345,\n    \"ipv6_prefixes\": {},\n    \"peers\": [\n      28716\n    ],\n    \"private\": false,\n    \"registry\": \"ripe\",\n    \"status\": \"allocated\"\n  },\n  \"query\": \"12345\",\n  \"status\": \"found\",\n  \"type\": \"as\"\n}\n```\n\nAn example query to an ASN not in the databases:\n\n```bash\n$ curl -s http://localhost/as/0 | jq\n{\n  \"result\": {},\n  \"query\": \"0\",\n  \"status\": \"not found\",\n  \"type\": \"as\"\n}\n```\n\n\n# Contributing\n\nAll properly formatted and sensible pull requests, issues and comments are\nwelcome.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeeb%2Fipnetdb-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeeb%2Fipnetdb-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeeb%2Fipnetdb-service/lists"}