{
"openapi": "3.1.0",
"info": {
"title": "MAC Address Lookup API",
"version": "2.0.0",
"summary": "Free, keyless MAC address vendor lookup against every IEEE registration.",
"description": "Resolves a MAC address, OUI, or any longer hardware identifier to the organization it is registered to, using the five IEEE Registration Authority registries (MA-L, MA-M, MA-S, IAB, CID), refreshed daily.\n\nNested assignments resolve to the most specific block, so a 36 bit MA-S inside a 24 bit prefix returns the real registrant rather than the parent.\n\n**No key, no signup.** Requests are rate limited per IP address and answered with `429` when over the limit. Every response is cacheable because the registry changes at most once a day, so please honour `Cache-Control` rather than re-requesting the same prefix.\n\nIf you are looking up more than a handful of addresses, see the [bulk downloads](https://macaddresslookup.app/vendormacs-xml) instead of calling the API once per address.",
"contact": {
"name": "MAC Address Lookup",
"url": "https://macaddresslookup.app/contact-us"
}
},
"externalDocs": {
"description": "API documentation",
"url": "https://macaddresslookup.app/api"
},
"servers": [
{
"url": "https://macaddresslookup.app"
}
],
"tags": [
{
"name": "Lookup",
"description": "Version 2. Use these for new integrations."
},
{
"name": "Version 1",
"description": "Returns the registrant address as a single field. Still supported."
},
{
"name": "Legacy paths",
"description": "The format-first URL shape from the original site. Returns the version 2 shape."
},
{
"name": "Operations",
"description": "For monitoring the service itself, not for looking anything up."
}
],
"paths": {
"/api/v2/{mac}": {
"get": {
"operationId": "lookupV2",
"summary": "Look up a MAC address",
"description": "Returns the most specific IEEE assignment containing the address, as JSON.",
"tags": [
"Lookup"
],
"parameters": [
{
"$ref": "#/components/parameters/Mac"
}
],
"responses": {
"200": {
"description": "The assignment containing the address, as an array with exactly one element.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/AssignmentV2"
}
},
"example": [
{
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"addressL1": "501-1015 rue William",
"addressL2": "Montreal Quebec H3C 1P4",
"addressL3": "",
"country": "CA",
"type": "MA-S"
}
]
}
}
},
"204": {
"$ref": "#/components/responses/NotRegistered"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/v2/{mac}/{format}": {
"get": {
"operationId": "lookupV2Format",
"summary": "Look up a MAC address in a chosen format",
"description": "Same result as `/api/v2/{mac}`, rendered as JSON, XML, CSV, or pipe-delimited text.",
"tags": [
"Lookup"
],
"parameters": [
{
"$ref": "#/components/parameters/Mac"
},
{
"$ref": "#/components/parameters/Format"
}
],
"responses": {
"200": {
"description": "The assignment containing the address. Only the media type matching the `format` path segment is returned.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/AssignmentV2"
}
},
"example": [
{
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"addressL1": "501-1015 rue William",
"addressL2": "Montreal Quebec H3C 1P4",
"addressL3": "",
"country": "CA",
"type": "MA-S"
}
]
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/AssignmentV2"
},
"example": "\r\n\r\n 001BC5094000\r\n 001BC5094FFF\r\n 119269834752\r\n 119269838847\r\n reelyActive\r\n 501-1015 rue William\r\n Montreal Quebec H3C 1P4\r\n \r\n CA\r\n MA-S\r\n"
},
"text/csv": {
"schema": {
"type": "string"
},
"example": "\"001BC5094000\",\"001BC5094FFF\",\"119269834752\",\"119269838847\",\"reelyActive\",\"501-1015 rue William\",\"Montreal Quebec H3C 1P4\",\"\",\"CA\",\"MA-S\""
},
"text/plain": {
"schema": {
"type": "string"
},
"example": "001BC5094000|001BC5094FFF|119269834752|119269838847|reelyActive|501-1015 rue William|Montreal Quebec H3C 1P4||CA|MA-S"
}
}
},
"204": {
"$ref": "#/components/responses/NotRegistered"
},
"400": {
"$ref": "#/components/responses/BadRequestAnyFormat"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/v1/{mac}": {
"get": {
"operationId": "lookupV1",
"summary": "Look up a MAC address (version 1)",
"description": "Version 1 shape: the registrant address is the single `address` field, holding its first line.",
"tags": [
"Version 1"
],
"parameters": [
{
"$ref": "#/components/parameters/Mac"
}
],
"responses": {
"200": {
"description": "The assignment containing the address, as an array with exactly one element.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/AssignmentV1"
}
},
"example": [
{
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"address": "501-1015 rue William",
"country": "CA",
"type": "MA-S"
}
]
}
}
},
"204": {
"$ref": "#/components/responses/NotRegistered"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/v1/{mac}/{format}": {
"get": {
"operationId": "lookupV1Format",
"summary": "Look up a MAC address in a chosen format (version 1)",
"description": "Same result as `/api/v1/{mac}`, rendered as JSON, XML, CSV, or pipe-delimited text.",
"tags": [
"Version 1"
],
"parameters": [
{
"$ref": "#/components/parameters/Mac"
},
{
"$ref": "#/components/parameters/Format"
}
],
"responses": {
"200": {
"description": "The assignment containing the address. Only the media type matching the `format` path segment is returned.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/AssignmentV1"
}
},
"example": [
{
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"address": "501-1015 rue William",
"country": "CA",
"type": "MA-S"
}
]
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/AssignmentV1"
},
"example": "\r\n\r\n 001BC5094000\r\n 001BC5094FFF\r\n 119269834752\r\n 119269838847\r\n reelyActive\r\n 501-1015 rue William\r\n CA\r\n MA-S\r\n"
},
"text/csv": {
"schema": {
"type": "string"
},
"example": "\"001BC5094000\",\"001BC5094FFF\",\"119269834752\",\"119269838847\",\"reelyActive\",\"501-1015 rue William\",\"CA\",\"MA-S\""
},
"text/plain": {
"schema": {
"type": "string"
},
"example": "001BC5094000|001BC5094FFF|119269834752|119269838847|reelyActive|501-1015 rue William|CA|MA-S"
}
}
},
"204": {
"$ref": "#/components/responses/NotRegistered"
},
"400": {
"$ref": "#/components/responses/BadRequestAnyFormat"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/api/{format}/{mac}": {
"get": {
"operationId": "lookupLegacy",
"summary": "Look up a MAC address, format first",
"description": "Equivalent to `/api/v2/{mac}/{format}`. Kept so integrations written against the original site keep working.",
"tags": [
"Legacy paths"
],
"parameters": [
{
"$ref": "#/components/parameters/Mac"
},
{
"$ref": "#/components/parameters/Format"
}
],
"responses": {
"200": {
"description": "The assignment containing the address. Only the media type matching the `format` path segment is returned.",
"headers": {
"Cache-Control": {
"$ref": "#/components/headers/CacheControl"
}
},
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"$ref": "#/components/schemas/AssignmentV2"
}
},
"example": [
{
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"addressL1": "501-1015 rue William",
"addressL2": "Montreal Quebec H3C 1P4",
"addressL3": "",
"country": "CA",
"type": "MA-S"
}
]
},
"application/xml": {
"schema": {
"$ref": "#/components/schemas/AssignmentV2"
},
"example": "\r\n\r\n 001BC5094000\r\n 001BC5094FFF\r\n 119269834752\r\n 119269838847\r\n reelyActive\r\n 501-1015 rue William\r\n Montreal Quebec H3C 1P4\r\n \r\n CA\r\n MA-S\r\n"
},
"text/csv": {
"schema": {
"type": "string"
},
"example": "\"001BC5094000\",\"001BC5094FFF\",\"119269834752\",\"119269838847\",\"reelyActive\",\"501-1015 rue William\",\"Montreal Quebec H3C 1P4\",\"\",\"CA\",\"MA-S\""
},
"text/plain": {
"schema": {
"type": "string"
},
"example": "001BC5094000|001BC5094FFF|119269834752|119269838847|reelyActive|501-1015 rue William|Montreal Quebec H3C 1P4||CA|MA-S"
}
}
},
"204": {
"$ref": "#/components/responses/NotRegistered"
},
"400": {
"$ref": "#/components/responses/BadRequestAnyFormat"
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
},
"/healthcheck": {
"get": {
"operationId": "healthcheck",
"summary": "Service health",
"description": "Runs a real lookup on every request, so a 200 means nginx, the FastCGI socket, a php-fpm worker, the database file, and the data in it all work. Never cached.\n\nIntended for an uptime monitor. `stale` means the registry data is older than the deployment's threshold: the site is serving normally, so it answers 200 and does not spend the uptime percentage. Match on `\"status\":\"ok\"` to alert on it separately.",
"tags": [
"Operations"
],
"responses": {
"200": {
"description": "The lookup works. `status` is `ok`, or `stale` when the data is older than the threshold.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
},
"example": {
"status": "ok",
"checks": {
"database": {
"ok": true,
"lookup_ms": 0.4
},
"data": {
"generated": "2026-09-17T14:20:23Z",
"age_hours": 19.4,
"stale": false,
"assignments": 58302
}
},
"time": "2026-09-18T09:55:01Z"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"503": {
"description": "The lookup failed. `status` is `degraded` and `checks.database.error` says why.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
},
"example": {
"status": "degraded",
"checks": {
"database": {
"ok": false,
"lookup_ms": 0.2,
"error": "unable to open database file"
},
"data": {
"generated": null,
"age_hours": null,
"stale": true,
"assignments": null
}
},
"time": "2026-09-18T09:55:01Z"
}
}
}
}
}
}
},
"/metrics": {
"get": {
"operationId": "metrics",
"summary": "Prometheus metrics",
"description": "The Prometheus text exposition format, covering the dataset age and counts, the lookup probe, OPcache, nginx connection counters, and php-fpm worker saturation.\n\nRequires `Authorization: Bearer `, configured per deployment. A missing or wrong token, and a deployment with no token configured at all, both answer `404`.",
"tags": [
"Operations"
],
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "The metrics.",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "# HELP mvl_data_age_seconds How long ago that was. The figure to alert on.\n# TYPE mvl_data_age_seconds gauge\nmvl_data_age_seconds 69878\n# HELP mvl_lookup_probe_success 1 when a known MAC address still resolves to its registrant.\n# TYPE mvl_lookup_probe_success gauge\nmvl_lookup_probe_success 1"
}
}
},
"404": {
"description": "No token was supplied, the token was wrong, or this deployment has no metrics token configured.",
"content": {
"text/plain": {
"schema": {
"type": "string"
},
"example": "Not found"
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "The token configured for this deployment as METRICS_TOKEN."
}
},
"parameters": {
"Mac": {
"name": "mac",
"in": "path",
"required": true,
"description": "A MAC address, OUI, or longer identifier in any common notation: colons, dashes, dots, or bare hex. At least six hex digits are required. Anything beyond the matched prefix is ignored, so an EUI-64 or IPv6 interface identifier resolves too.",
"schema": {
"type": "string",
"minLength": 6
},
"examples": {
"colons": {
"summary": "Colon separated",
"value": "00:1B:C5:09:40:00"
},
"bare": {
"summary": "Bare hex",
"value": "001BC5094000"
},
"oui": {
"summary": "OUI only",
"value": "00-00-0C"
},
"cisco": {
"summary": "Cisco dotted",
"value": "0000.0c11.2233"
}
}
},
"Format": {
"name": "format",
"in": "path",
"required": true,
"description": "Response format: `json` (application/json), `xml` (application/xml), `csv` (text/csv, one quoted row with no header), or `pipe` (text/plain, one pipe-delimited row). Fields appear in the same order as the JSON keys.",
"schema": {
"type": "string",
"enum": [
"json",
"xml",
"csv",
"pipe"
],
"default": "json"
}
}
},
"headers": {
"CacheControl": {
"description": "Responses are public and cacheable for a day.",
"schema": {
"type": "string"
},
"example": "public, max-age=86400, stale-while-revalidate=604800"
}
},
"schemas": {
"AssignmentV2": {
"type": "object",
"xml": {
"name": "result"
},
"required": [
"startHex",
"endHex",
"startDec",
"endDec",
"company",
"addressL1",
"addressL2",
"addressL3",
"country",
"type"
],
"properties": {
"startHex": {
"type": "string",
"pattern": "^[0-9A-F]{12}$",
"description": "First address in the assigned block, as 12 upper-case hex digits."
},
"endHex": {
"type": "string",
"pattern": "^[0-9A-F]{12}$",
"description": "Last address in the assigned block, as 12 upper-case hex digits."
},
"startDec": {
"type": "integer",
"format": "int64",
"description": "startHex as a decimal integer."
},
"endDec": {
"type": "integer",
"format": "int64",
"description": "endHex as a decimal integer."
},
"company": {
"type": "string",
"description": "Registrant organization name, verbatim from the IEEE registry."
},
"addressL1": {
"type": "string",
"description": "First line of the registrant address, or an empty string."
},
"addressL2": {
"type": "string",
"description": "Second line of the registrant address, or an empty string."
},
"addressL3": {
"type": "string",
"description": "Third line of the registrant address, or an empty string."
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code of the registrant, or an empty string when the registry has none."
},
"type": {
"type": "string",
"enum": [
"MA-L",
"MA-M",
"MA-S",
"IAB",
"CID"
],
"description": "Which IEEE registry the block comes from."
}
},
"example": {
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"addressL1": "501-1015 rue William",
"addressL2": "Montreal Quebec H3C 1P4",
"addressL3": "",
"country": "CA",
"type": "MA-S"
}
},
"AssignmentV1": {
"type": "object",
"xml": {
"name": "result"
},
"required": [
"startHex",
"endHex",
"startDec",
"endDec",
"company",
"address",
"country",
"type"
],
"properties": {
"startHex": {
"type": "string",
"pattern": "^[0-9A-F]{12}$",
"description": "First address in the assigned block, as 12 upper-case hex digits."
},
"endHex": {
"type": "string",
"pattern": "^[0-9A-F]{12}$",
"description": "Last address in the assigned block, as 12 upper-case hex digits."
},
"startDec": {
"type": "integer",
"format": "int64",
"description": "startHex as a decimal integer."
},
"endDec": {
"type": "integer",
"format": "int64",
"description": "endHex as a decimal integer."
},
"company": {
"type": "string",
"description": "Registrant organization name, verbatim from the IEEE registry."
},
"address": {
"type": "string",
"description": "First line of the registrant address, or an empty string."
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code of the registrant, or an empty string when the registry has none."
},
"type": {
"type": "string",
"enum": [
"MA-L",
"MA-M",
"MA-S",
"IAB",
"CID"
],
"description": "Which IEEE registry the block comes from."
}
},
"example": {
"startHex": "001BC5094000",
"endHex": "001BC5094FFF",
"startDec": 119269834752,
"endDec": 119269838847,
"company": "reelyActive",
"address": "501-1015 rue William",
"country": "CA",
"type": "MA-S"
}
},
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "A human readable reason."
}
}
},
"Health": {
"type": "object",
"required": [
"status",
"checks",
"time"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"stale",
"degraded"
],
"description": "`ok` with fresh data, `stale` when the data is older than the threshold, `degraded` when the lookup failed."
},
"checks": {
"type": "object",
"required": [
"database",
"data"
],
"properties": {
"database": {
"type": "object",
"required": [
"ok",
"lookup_ms"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Whether the probe lookup returned its expected registrant."
},
"lookup_ms": {
"type": "number",
"description": "How long that lookup took, in milliseconds."
},
"error": {
"type": "string",
"description": "Present only when the lookup failed."
}
}
},
"data": {
"type": "object",
"required": [
"generated",
"age_hours",
"stale",
"assignments"
],
"properties": {
"generated": {
"type": [
"string",
"null"
],
"description": "When the IEEE registries were last imported, or null if that cannot be read."
},
"age_hours": {
"type": [
"number",
"null"
],
"description": "How long ago that was."
},
"stale": {
"type": "boolean",
"description": "Whether that age is past this deployment's threshold. Unknown age counts as stale."
},
"assignments": {
"type": [
"integer",
"null"
],
"description": "Assignments in the database."
}
}
}
}
},
"time": {
"type": "string",
"description": "When this response was generated, in UTC."
}
}
}
},
"responses": {
"NotRegistered": {
"description": "The address is well formed but falls inside no IEEE assignment. There is no body."
},
"BadRequest": {
"description": "Fewer than six hex digits were supplied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Supply a MAC address with at least six hex digits."
}
}
}
},
"BadRequestAnyFormat": {
"description": "Fewer than six hex digits were supplied. The body is in the requested format; csv and pipe return the bare message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Supply a MAC address with at least six hex digits."
}
},
"application/xml": {
"schema": {
"type": "string",
"xml": {
"name": "error"
}
},
"example": "\r\nSupply a MAC address with at least six hex digits."
},
"text/csv": {
"schema": {
"type": "string"
},
"example": "Supply a MAC address with at least six hex digits."
},
"text/plain": {
"schema": {
"type": "string"
},
"example": "Supply a MAC address with at least six hex digits."
}
}
},
"RateLimited": {
"description": "Too many requests from this IP address. Always JSON, whatever format was requested.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": "Too many requests. Slow down and try again."
}
}
}
}
}
}
}