{ "openapi": "3.1.0", "info": { "title": "Pinloft API", "version": "1.0.0", "summary": "Free geocoding API and MCP server: address to latitude/longitude with US Census county, tract and block FIPS codes, districts and reverse geocoding.", "description": "Paid API keys from $19/month (Starter: 25,000 calls a month); free tier 100 calls a day per IP with no key. Buy: https://pinloft.cybermaxtools.com/buy/starter?s=lead · all plans: https://pinloft.cybermaxtools.com/docs#pricing\n\nPricing: free tier 100 calls/day per IP, no key. Paid API keys: Starter $19/month = 25,000 calls/month; Pro $49/month = 100,000 calls/month; Pay as you go $5 = 5,000 calls (one-time pack); Starter yearly $190/year = 25,000 calls/month; Pro yearly $490/year = 100,000 calls/month. Get a key: https://pinloft.cybermaxtools.com/docs#pricing\n\nType an address, get latitude and longitude, a cleaned address and, in the US, the county, Census tract and block FIPS codes from the official US Census geocoder. Worldwide addresses and reverse lookups use OpenStreetMap.\n\nFree tier: 20 calls per minute per IP address. Up to 5 addresses or points per call. Up to 3 OpenStreetMap lookups per call (non-US addresses, US misses, reverse); US addresses use the Census geocoder. About 15 seconds per call at most. Free tier: 100 calls a day per IP, no key. Paid API keys from $19/month (or $5 pay-as-you-go) lift the daily limit. OSM results: © OpenStreetMap contributors (ODbL). No key needed. Remote MCP server: https://pinloft.cybermaxtools.com/mcp", "contact": { "name": "CyberMax", "url": "https://cybermax-tools-cybermax.static.hf.space/" }, "license": { "name": "Proprietary (free tier + paid API keys)", "identifier": "LicenseRef-CyberMax" }, "x-x402": { "protocol": "x402", "versions": [ 1, 2 ], "scheme": "exact", "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "currency": "USDC", "price": { "perCallUsd": 0.002 }, "payPerCallEndpoints": [ "/x402/api/geocode", "/x402/api/reverse" ], "alsoOn": "the plain endpoints answer 402 with the same terms once the free daily quota is used up (no key sent)", "headers": { "request": [ "X-PAYMENT (v1)", "PAYMENT-SIGNATURE (v2)" ], "response": [ "X-PAYMENT-RESPONSE", "PAYMENT-RESPONSE" ] } }, "x-pricing": { "api": "Pinloft API", "currency": "USD", "free": { "price": 0, "callsPerDayPerIp": 100, "perMinutePerIp": 20, "key": "none needed" }, "plans": [ { "id": "starter", "name": "Starter", "price": 19, "billing": "per month", "calls": 25000, "per": "calendar month (UTC)", "perMinute": 60, "buy": "https://pinloft.cybermaxtools.com/buy/starter?s=openapi" }, { "id": "pro", "name": "Pro", "price": 49, "billing": "per month", "calls": 100000, "per": "calendar month (UTC)", "perMinute": 120, "buy": "https://pinloft.cybermaxtools.com/buy/pro?s=openapi" }, { "id": "pack", "name": "Pay as you go", "price": 5, "billing": "one-time", "calls": 5000, "per": "until used", "perMinute": 60, "buy": "https://pinloft.cybermaxtools.com/buy/pack?s=openapi" }, { "id": "starter-yearly", "name": "Starter yearly", "price": 190, "billing": "per year", "calls": 25000, "per": "calendar month (UTC)", "perMinute": 60, "buy": "https://pinloft.cybermaxtools.com/buy/starter-yearly?s=openapi" }, { "id": "pro-yearly", "name": "Pro yearly", "price": 490, "billing": "per year", "calls": 100000, "per": "calendar month (UTC)", "perMinute": 120, "buy": "https://pinloft.cybermaxtools.com/buy/pro-yearly?s=openapi" } ], "unit": "calls", "howToUse": { "header": "x-api-key: YOUR_KEY", "alt": [ "Authorization: Bearer YOUR_KEY", "?key=YOUR_KEY" ], "mcp": "send the key as Authorization: Bearer YOUR_KEY", "usage": "https://pinloft.cybermaxtools.com/key" }, "manageKey": "https://pinloft.cybermaxtools.com/manage", "payments": "Stripe Checkout: card, Apple Pay, Google Pay, Link; sales tax/VAT handled by Stripe. Cancel any time at https://pinloft.cybermaxtools.com/manage." } }, "servers": [ { "url": "https://pinloft.cybermaxtools.com" }, { "url": "https://pinloft.cybermax-tools.workers.dev" } ], "paths": { "/api/geocode": { "get": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.", "operationId": "geocodeAddressesGet", "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Up to 5 addresses separated by | (or repeat the parameter)", "schema": { "type": "string" }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" }, { "name": "districts", "in": "query", "required": false, "description": "Add districts for US matches", "schema": { "type": "boolean", "default": false } }, { "name": "country", "in": "query", "required": false, "description": "\"auto\" (default), \"US\" or ISO-2 codes like \"de,at\" to steer non-US lookups", "schema": { "type": "string", "default": "auto" } }, { "name": "language", "in": "query", "required": false, "description": "Language for OpenStreetMap names (default en)", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (100/day per IP) or rate/plan limit reached; the body has an upgrade link.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.", "operationId": "geocodeAddressesPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "description": "Addresses, one per item, e.g. \"1600 Pennsylvania Ave NW, Washington, DC 20500\" or \"10 Downing St, London\". Up to 5." }, "districts": { "type": "boolean" }, "country": { "type": "string" }, "language": { "type": "string" } }, "required": [ "addresses" ] }, "example": { "addresses": [ "233 S Wacker Dr, Chicago, IL 60606", "10 Downing St, London" ], "districts": true } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (100/day per IP) or rate/plan limit reached; the body has an upgrade link.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/reverse": { "get": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.", "operationId": "reverseGeocodeGet", "parameters": [ { "name": "lat", "in": "query", "required": false, "description": "Latitude (with lon)", "schema": { "type": "number" }, "example": 40.7484 }, { "name": "lon", "in": "query", "required": false, "description": "Longitude (with lat)", "schema": { "type": "number" }, "example": -73.9857 }, { "name": "coords", "in": "query", "required": false, "description": "Or up to 5 \"lat,lon\" pairs separated by |", "schema": { "type": "string" }, "example": "40.7484,-73.9857|51.5007,-0.1246" } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (100/day per IP) or rate/plan limit reached; the body has an upgrade link.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.", "operationId": "reverseGeocodePost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "coordinates": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "\"lat,lon\" strings" } }, "required": [ "coordinates" ] }, "example": { "coordinates": [ "40.7484,-73.9857", "51.5007,-0.1246" ] } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Free tier used up (100/day per IP) or rate/plan limit reached; the body has an upgrade link.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/x402/api/geocode": { "get": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide) (pay per call in USDC via x402, no key)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "geocodeAddressesGetPayPerCall", "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Up to 5 addresses separated by | (or repeat the parameter)", "schema": { "type": "string" }, "example": "1600 Pennsylvania Ave NW, Washington, DC 20500" }, { "name": "districts", "in": "query", "required": false, "description": "Add districts for US matches", "schema": { "type": "boolean", "default": false } }, { "name": "country", "in": "query", "required": false, "description": "\"auto\" (default), \"US\" or ISO-2 codes like \"de,at\" to steer non-US lookups", "schema": { "type": "string", "default": "auto" } }, { "name": "language", "in": "query", "required": false, "description": "Language for OpenStreetMap names (default en)", "schema": { "type": "string", "default": "en" } } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Pinloft" ], "summary": "Geocode up to 5 addresses (US Census first, OpenStreetMap worldwide) (pay per call in USDC via x402, no key)", "description": "US addresses go to the US Census Bureau geocoder (public domain) and come back with county, tract, block group and block FIPS. Other addresses and US misses use OpenStreetMap (Nominatim, Photon fallback). districts=true adds congressional and state legislative districts, place, metro area, school district and ZCTA for US matches.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "geocodeAddressesPostPayPerCall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "description": "Addresses, one per item, e.g. \"1600 Pennsylvania Ave NW, Washington, DC 20500\" or \"10 Downing St, London\". Up to 5." }, "districts": { "type": "boolean" }, "country": { "type": "string" }, "language": { "type": "string" } }, "required": [ "addresses" ] }, "example": { "addresses": [ "233 S Wacker Dr, Chicago, IL 60606", "10 Downing St, London" ], "districts": true } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "example": { "results": [ { "id": "1", "query": "233 S Wacker Dr, Chicago, IL 60606", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 41.8789195, "longitude": -87.6366023, "formattedAddress": "233 S WACKER DR, CHICAGO, IL, 60606", "matchType": "exact", "confidence": 1, "houseNumber": "233", "street": "S WACKER DR", "city": "CHICAGO", "county": "Cook County", "state": "Illinois", "stateCode": "IL", "postcode": "60606", "country": "United States", "countryCode": "US", "stateFips": "17", "countyFips": "17031", "tractFips": "17031839100", "blockGroupFips": "170318391002", "blockFips": "170318391002008", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "2", "query": "1600 Pennsylvania Ave NW, Washington, DC 20500", "queryType": "address", "status": "matched", "source": "us-census", "latitude": 38.8987026, "longitude": -77.0351892, "formattedAddress": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500", "matchType": "exact", "confidence": 1, "houseNumber": "1600", "street": "PENNSYLVANIA AVE NW", "city": "WASHINGTON", "county": "District of Columbia", "state": "District of Columbia", "stateCode": "DC", "postcode": "20500", "country": "United States", "countryCode": "US", "stateFips": "11", "countyFips": "11001", "tractFips": "11001980000", "blockGroupFips": "110019800001", "blockFips": "110019800001034", "osmType": null, "osmId": null, "placeType": "address", "districts": null, "attribution": "US Census Bureau Geocoder (public domain), TIGER/Line current benchmark", "note": null }, { "id": "3", "query": "10 Downing St, London", "queryType": "address", "status": "matched", "source": "openstreetmap", "latitude": 51.5034878, "longitude": -0.1276965, "formattedAddress": "10 Downing Street, 10, Downing Street, Westminster, Covent Garden, City of Westminster, Greater London, England, SW1A 2AA, United Kingdom", "matchType": "rooftop_or_building", "confidence": 0.9, "houseNumber": "10", "street": "Downing Street", "city": "City of Westminster", "county": null, "state": "England", "stateCode": "ENG", "postcode": "SW1A 2AA", "country": "United Kingdom", "countryCode": "GB", "stateFips": null, "countyFips": null, "tractFips": null, "blockGroupFips": null, "blockFips": null, "osmType": "relation", "osmId": 1879842, "placeType": "office", "districts": null, "attribution": "Data © OpenStreetMap contributors, ODbL 1.0 (openstreetmap.org/copyright); geocoded via Nominatim or Photon", "note": null } ], "count": 3 } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } }, "/x402/api/reverse": { "get": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts) (pay per call in USDC via x402, no key)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "reverseGeocodeGetPayPerCall", "parameters": [ { "name": "lat", "in": "query", "required": false, "description": "Latitude (with lon)", "schema": { "type": "number" }, "example": 40.7484 }, { "name": "lon", "in": "query", "required": false, "description": "Longitude (with lat)", "schema": { "type": "number" }, "example": -73.9857 }, { "name": "coords", "in": "query", "required": false, "description": "Or up to 5 \"lat,lon\" pairs separated by |", "schema": { "type": "string" }, "example": "40.7484,-73.9857|51.5007,-0.1246" } ], "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } }, "post": { "tags": [ "Pinloft" ], "summary": "Reverse geocode up to 5 points (street address + US FIPS and districts) (pay per call in USDC via x402, no key)", "description": "Nearest street address from OpenStreetMap plus, for US points, state/county/tract/block FIPS and districts from the US Census geocoder.\n\nPay per call with x402: $0.002 per call in USDC on Base. No key, no account: an unpaid call returns 402 with the payment requirements; retry with the X-PAYMENT (x402 v1) or PAYMENT-SIGNATURE (v2) header.", "operationId": "reverseGeocodePostPayPerCall", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "coordinates": { "type": "array", "items": { "type": "string" }, "maxItems": 5, "description": "\"lat,lon\" strings" } }, "required": [ "coordinates" ] }, "example": { "coordinates": [ "40.7484,-73.9857", "51.5007,-0.1246" ] } } } }, "responses": { "200": { "description": "Results (same field names as the bulk version's dataset records) plus the free-tier limits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment Required: x402 payment requirements (body: x402Version 1 accepts[]; header PAYMENT-REQUIRED: x402 v2)." }, "504": { "description": "Took too long; ask for fewer items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002" }, "protocols": [ { "x402": { "version": [ 1, 2 ], "network": [ "base", "eip155:8453" ], "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "scheme": "exact" } } ] } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "retryAfterSeconds": { "type": "integer" }, "limits": { "type": "object" } }, "required": [ "error", "message" ] } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Optional. Paid plan key from https://pinloft.cybermaxtools.com/docs#pricing; leave out for the free tier." }, "BearerKey": { "type": "http", "scheme": "bearer", "description": "Same key as a Bearer token." } } }, "x-mcp-server": "https://pinloft.cybermaxtools.com/mcp", "externalDocs": { "description": "Get an API key (pricing)", "url": "https://pinloft.cybermaxtools.com/docs#pricing" }, "security": [ {}, { "ApiKeyHeader": [] }, { "BearerKey": [] } ] }