parseapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db102dc0d021fa26f14dfdb337e38ead8d770d6a49b99d9b185ff4caf1c1cc17
+  data.tar.gz: d78a937301d8084f9a3ddfb0004419931309448223dbbe98302effcef101ba8c
+SHA512:
+  metadata.gz: 16e8e88149664cb0c07e72fda814f32ae22ca630ddc67e0f950e12d4a4d4542f41169b4b73f0cfe73565f36318eadbe13e64dc9be8dfaccdec2721d583d51938
+  data.tar.gz: b90d2a5589adc9c5c97e0ff8499cdd847e8a332133aec087dcdd26cb51233faca40434342245658c894231ab0126c4b5466d8523f61969243e4813aece87e1e7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 parseAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# parseapi
+
+Official parseAPI client for Ruby.
+
+```bash
+gem install parseapi
+```
+
+```ruby
+require 'parseapi'
+
+parse = ParseAPI.new('your-api-key')
+country = parse.country('US')
+```
+
+Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEAPI_KEY` from the environment.
+
+## Calls
+
+One method per endpoint, named after the route.
+
+```ruby
+parse.ip('8.8.8.8')
+parse.ip_self
+parse.email('hello@gmail.com')
+parse.phone('+14155552671')
+parse.postal('28202', country: 'US')
+parse.postal_nearby('28202', country: 'US', radius: 40)
+parse.postal_distance('28202', '10001', country: 'US')
+parse.city('charlotte', country: 'US')
+parse.city_id('city_mb8mbqrkz8zb')
+parse.city_search('char', country: 'US', limit: 10)
+parse.city_nearest(35.2271, -80.8431)
+parse.country('US')
+parse.country_states('US')
+parse.state('NC', country: 'US')
+parse.state_districts('NC', country: 'US')
+parse.district('37081')
+parse.continent('NA')
+parse.continent_countries('NA')
+parse.currency('USD')
+parse.currency_rate('USD', 'EUR')
+parse.language('en')
+parse.timezone('America/New_York')
+parse.holiday('US', year: 2026)
+parse.holiday_date('US', '2026-12-25')
+parse.elevation(35.2271, -80.8431)
+parse.point(36.0726, -79.792)
+parse.weather(40.7128, -74.006)
+parse.domain('example.com')
+parse.mx('example.com')
+parse.useragent(ua_string)
+parse.emoji('rocket')
+parse.emoji_search('fire')
+```
+
+Responses are plain hashes, exactly the JSON the API returns.
+
+## Deep
+
+Pass `deep: true` to include the nested `deep` object with richer fields.
+
+```ruby
+ip = parse.ip('52.94.76.10', deep: true)
+ip['deep']['datacenter'] # true
+```
+
+## Errors
+
+Every non-2xx response raises `ParseAPI::Error` with `status`, `code`, `docs`, and `request_id`. Branch on `code`.
+
+```ruby
+begin
+  parse.city('atlantis')
+rescue ParseAPI::Error => e
+  if e.code == 'not_found'
+    # no such city
+  end
+end
+```
+
+## Options
+
+```ruby
+parse = ParseAPI.new(
+  'your-api-key',
+  timeout: 10, # per-attempt timeout in seconds
+  retries: 2   # automatic retries on network errors, 429, and 5xx
+)
+```
+
+Requires Ruby 3.0 or later. Standard library only, zero dependencies.
+
+## Docs
+
+Full field reference for every endpoint: [parseapi.com/docs](https://parseapi.com/docs)

data/lib/parseapi/client.rb

@@ -0,0 +1,257 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module ParseAPI
+	# Every non-2xx response from the API. Branch on +code+, never on the message.
+	class Error < StandardError
+		attr_reader :status, :code, :docs, :request_id
+
+		def initialize(status:, code:, message:, docs: nil, request_id: nil)
+			super(message)
+			@status = status
+			@code = code
+			@docs = docs
+			@request_id = request_id
+		end
+	end
+
+	class Client
+		DEFAULT_BASE_URL = 'https://api.parseapi.com'.freeze
+		DEFAULT_TIMEOUT = 10
+		DEFAULT_RETRIES = 2
+		RETRY_STATUS = [429, 500, 502, 503, 504].freeze
+		RETRY_AFTER_CAP = 5.0
+		NETWORK_ERRORS = [
+			Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ETIMEDOUT,
+			Net::OpenTimeout, Net::ReadTimeout, IOError, EOFError, SocketError
+		].freeze
+
+		def initialize(api_key = nil, base_url: nil, timeout: nil, retries: nil)
+			@api_key = api_key || ENV['PARSEAPI_KEY']
+			raise ArgumentError, 'parseapi: missing API key. Pass one or set PARSEAPI_KEY.' if @api_key.nil? || @api_key.empty?
+
+			@base_url = URI((base_url || ENV['PARSEAPI_BASE_URL'] || DEFAULT_BASE_URL).sub(%r{/+\z}, ''))
+			@timeout = timeout || DEFAULT_TIMEOUT
+			@retries = retries || DEFAULT_RETRIES
+			@http = nil
+		end
+
+		# --- Lookup methods (one per endpoint, named after the route) ---
+
+		def ip(ip, deep: false)
+			get("/ip/#{seg(ip)}", deep: deep)
+		end
+
+		def ip_self(deep: false)
+			get('/ip', deep: deep)
+		end
+
+		def continent(code)
+			get("/continent/#{seg(code)}")
+		end
+
+		def continent_countries(code)
+			get("/continent/#{seg(code)}/countries")
+		end
+
+		def country(code)
+			get("/country/#{seg(code)}")
+		end
+
+		def country_states(code)
+			get("/country/#{seg(code)}/states")
+		end
+
+		def state(code, country:)
+			get("/state/#{seg(code)}", country: country)
+		end
+
+		def state_districts(code, country:)
+			get("/state/#{seg(code)}/districts", country: country)
+		end
+
+		def district(code, country: nil)
+			get("/district/#{seg(code)}", country: country)
+		end
+
+		def city(name, country: nil, state: nil)
+			get("/city/#{seg(name)}", country: country, state: state)
+		end
+
+		def city_id(id)
+			get("/city/id/#{seg(id)}")
+		end
+
+		def city_search(q, country: nil, state: nil, limit: nil)
+			get('/city', q: q, country: country, state: state, limit: limit)
+		end
+
+		def city_nearest(lat, lon)
+			get('/city', lat: lat, lon: lon)
+		end
+
+		def postal(code, country:)
+			get("/postal/#{seg(code)}", country: country)
+		end
+
+		def postal_nearby(code, country:, radius: nil, unit: nil)
+			get("/postal/#{seg(code)}/nearby", country: country, radius: radius, unit: unit)
+		end
+
+		def postal_distance(from, to, country:)
+			get("/postal/#{seg(from)}/distance/#{seg(to)}", country: country)
+		end
+
+		def email(email, deep: false)
+			get("/email/#{seg(email)}", deep: deep)
+		end
+
+		def phone(number, country: nil, deep: false)
+			get("/phone/#{seg(number)}", country: country, deep: deep)
+		end
+
+		def domain(domain, deep: false)
+			get("/domain/#{seg(domain)}", deep: deep)
+		end
+
+		def mx(domain)
+			get("/mx/#{seg(domain)}")
+		end
+
+		def useragent(ua, deep: false)
+			get('/useragent', { deep: deep }, { 'User-Agent' => ua })
+		end
+
+		def currency(code)
+			get("/currency/#{seg(code)}")
+		end
+
+		def currency_rate(base, quote)
+			get("/currency/#{seg(base)}/#{seg(quote)}")
+		end
+
+		def language(code)
+			get("/language/#{seg(code)}")
+		end
+
+		def timezone(id, at: nil)
+			get("/timezone/#{seg(id)}", at: at)
+		end
+
+		def holiday(country, year: nil)
+			get("/holiday/#{seg(country)}", year: year)
+		end
+
+		def holiday_date(country, date)
+			get("/holiday/#{seg(country)}/#{seg(date)}")
+		end
+
+		def elevation(lat, lon)
+			get('/elevation', lat: lat, lon: lon)
+		end
+
+		def point(lat, lon, deep: false)
+			get('/point', lat: lat, lon: lon, deep: deep)
+		end
+
+		def weather(lat, lon, deep: false)
+			get('/weather', lat: lat, lon: lon, deep: deep)
+		end
+
+		def emoji(emoji)
+			get("/emoji/#{seg(emoji)}")
+		end
+
+		def emoji_search(q, limit: nil)
+			get('/emoji', q: q, limit: limit)
+		end
+
+		private
+
+		def seg(value)
+			URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+		end
+
+		def get(path, params = {}, headers = {})
+			query = params.reject { |_name, value| value.nil? || value == false }
+			uri = @base_url.dup
+			uri.path = path
+			uri.query = URI.encode_www_form(query) unless query.empty?
+
+			attempt = 0
+			loop do
+				begin
+					status, response_headers, body = execute(uri, request_headers(headers))
+				rescue *NETWORK_ERRORS
+					raise if attempt >= @retries
+
+					sleep(retry_delay(attempt, nil))
+					attempt += 1
+					next
+				end
+
+				return JSON.parse(body) if (200..299).cover?(status)
+
+				if RETRY_STATUS.include?(status) && attempt < @retries
+					sleep(retry_delay(attempt, response_headers['retry-after']))
+					attempt += 1
+					next
+				end
+
+				raise build_error(status, body)
+			end
+		end
+
+		def request_headers(extra)
+			{ 'X-API-Key' => @api_key, 'User-Agent' => "parseapi-ruby/#{VERSION}" }.merge(extra)
+		end
+
+		# Returns [status, headers_hash, body_string]. Overridden in tests.
+		def execute(uri, headers)
+			http = connection
+			request = Net::HTTP::Get.new(uri.request_uri)
+			headers.each { |name, value| request[name] = value }
+			response = http.request(request)
+			header_hash = {}
+			response.each_header { |name, value| header_hash[name.downcase] = value }
+			[response.code.to_i, header_hash, response.body || '']
+		end
+
+		def connection
+			if @http.nil?
+				@http = Net::HTTP.new(@base_url.host, @base_url.port)
+				@http.use_ssl = @base_url.scheme == 'https'
+				@http.open_timeout = @timeout
+				@http.read_timeout = @timeout
+				@http.keep_alive_timeout = 30
+			end
+			@http.start unless @http.started?
+			@http
+		end
+
+		def retry_delay(attempt, retry_after)
+			if retry_after
+				seconds = Float(retry_after, exception: false)
+				return [seconds, RETRY_AFTER_CAP].min if seconds && seconds >= 0
+			end
+			rand * 0.25 * (2**attempt)
+		end
+
+		def build_error(status, body)
+			parsed = begin
+				JSON.parse(body)
+			rescue JSON::ParserError
+				{}
+			end
+			parsed = {} unless parsed.is_a?(Hash)
+			Error.new(
+				status: status,
+				code: parsed['code'].is_a?(String) ? parsed['code'] : 'unknown_error',
+				message: parsed['message'].is_a?(String) ? parsed['message'] : "Request failed with status #{status}",
+				docs: parsed['docs'].is_a?(String) ? parsed['docs'] : nil,
+				request_id: parsed['request_id'].is_a?(String) ? parsed['request_id'] : nil
+			)
+		end
+	end
+end

data/lib/parseapi/version.rb

@@ -0,0 +1,3 @@
+module ParseAPI
+	VERSION = '0.1.0'.freeze
+end

data/lib/parseapi.rb

@@ -0,0 +1,13 @@
+require_relative 'parseapi/version'
+require_relative 'parseapi/client'
+
+# Official parseAPI client for Ruby.
+#
+#   parse = ParseAPI.new('your-api-key')
+#   parse.country('US')
+module ParseAPI
+	# Sugar so `ParseAPI.new` builds a Client.
+	def self.new(api_key = nil, **options)
+		Client.new(api_key, **options)
+	end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: parseapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- parseAPI
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-13 00:00:00.000000000 Z
+dependencies: []
+description: 
+email:
+- hello@parseapi.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/parseapi.rb
+- lib/parseapi/client.rb
+- lib/parseapi/version.rb
+homepage: https://parseapi.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://parseapi.com
+  source_code_uri: https://github.com/parseapi/ruby
+  documentation_uri: https://parseapi.com/docs
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official parseAPI client for Ruby. One key, minimal JSON, fast.
+test_files: []